{"openapi":"3.1.0","info":{"title":"Adanos Market Sentiment API","description":"\nThe Adanos API measures how much attention stocks and crypto tokens get on **Reddit**, **X/Twitter**, **financial news** and **Polymarket**. It shows whether that attention is bullish or bearish. A separate endpoint scores the sentiment of financial text you send. Reference coverage is 35,000+ stock tickers.\n\nThe core concepts across the API are **Buzz Score**, **Trend Detection** and directional **Sentiment**: they show what is moving, in which direction and on which platform.\n\n## Quickstart\n\n1. Create a free API key at [adanos.org/register](https://adanos.org/register). Store it in `ADANOS_API_KEY`, not in browser code or public repositories.\n2. Send it in the `X-API-Key` header. This call returns the three stocks with the most Reddit attention today (response shortened):\n\n```bash\ncurl \"https://api.adanos.org/reddit/stocks/v1/trending?limit=3\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\"\n```\n\n```json\n[\n  {\n    \"ticker\": \"TSLA\",\n    \"company_name\": \"Tesla, Inc.\",\n    \"buzz_score\": 87.5,\n    \"trend\": \"rising\",\n    \"sentiment_score\": 0.23\n  }\n]\n```\n\n## Platforms\n\n| Platform | Base path |\n|----------|-----------|\n| Reddit Stocks | `/reddit/stocks/v1` |\n| X/Twitter Stocks | `/x/stocks/v1` |\n| News Stocks | `/news/stocks/v1` |\n| Polymarket Stocks | `/polymarket/stocks/v1` |\n| Reddit Crypto | `/reddit/crypto/v1` |\n| Finance Sentiment | `/sentiment/v1` |\n\nEach stock platform offers `/trending`, `/stock/{ticker}`, `/compare` and `/search`.\n\n## Key metrics\n\n| Field | Meaning |\n|-------|---------|\n| `buzz_score` | Attention on one platform, from 0 to 100 |\n| `sentiment_score` | From `-1.0` (bearish) to `+1.0` (bullish). `null` when too few mentions take a side. |\n| `bullish_pct`, `bearish_pct` | Share of directional mentions that are bullish or bearish, in percent |\n| `trend` | `rising`, `falling` or `stable`. Compares activity in the last 3 days with the 3 days before; the share price plays no part. |\n\nA `null` value means the field has no data for this asset and period.\n\n## Limits and errors\n\n- Free keys allow 250 requests per month, 100 per minute and 30 days of history. The `X-RateLimit-*` headers show what is left.\n- After a `429`, wait the number of seconds in `Retry-After`. The monthly quota resets at `X-RateLimit-Reset-Monthly`.\n- Errors return JSON with a `detail` field. It holds a message, a list of invalid fields or an object with a `message`.\n- Responses carry an `X-Request-ID` header. Include it when you contact [support@adanos.org](mailto:support@adanos.org).\n\n## Notes\n\n- Set the period with `from` and `to` (UTC dates, `YYYY-MM-DD`). Without them, `/trending` and `/market-sentiment` show the current day. `/stock/{ticker}` and `/compare` show the last 7 days.\n- For AI agents, [`/llms.txt`](/llms.txt) describes the whole API in plain text.\n\n","termsOfService":"https://adanos.org/terms","contact":{"name":"API Support","url":"https://api.adanos.org/","email":"support@adanos.org"},"license":{"name":"MIT (OpenAPI document only)","url":"https://opensource.org/licenses/MIT"},"version":"1.53.4"},"servers":[{"url":"https://api.adanos.org","description":"Production"}],"paths":{"/reddit/stocks/v1/trending":{"get":{"tags":["Reddit Stocks"],"summary":"Trending stocks","description":"Returns the Reddit stocks with the strongest discussion activity in the selected period, ranked by `buzz_score`.\n\n**Includes:**\n- `buzz_score`: normalized 0-100 activity score used for ranking\n- `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals\n- `mentions`, `unique_posts`, `subreddit_count`, `total_upvotes`: attributed volume and engagement signals, including inherited thread-context mentions\n- `trend_history`: independent UTC-day buzz scores, oldest to newest; minimum 7 values; the live final value describes today so far and can differ from the selected-period `buzz_score`; missing days are `0.0`","operationId":"getTrendingStocks","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of results","examples":[10],"default":20,"title":"Limit"},"description":"Maximum number of results"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of items to skip for pagination","examples":[0],"default":0,"title":"Offset"},"description":"Number of items to skip for pagination"},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["stock","etf","all"],"type":"string"},{"type":"null"}],"description":"Filter by asset type. Omit or use 'all' for all assets.","examples":["stock"],"title":"Type"},"description":"Filter by asset type. Omit or use 'all' for all assets."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TrendingStock"},"title":"Response Gettrendingstocks"},"example":[{"ticker":"TSLA","company_name":"Tesla, Inc.","buzz_score":87.5,"trend":"rising","mentions":342,"unique_posts":45,"subreddit_count":8,"sentiment_score":0.23,"bullish_pct":45,"bearish_pct":18,"total_upvotes":15234,"trend_history":[45.2,52.1,48.7,67.3,72.1,78.4,87.5]}]}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=30"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Gettrendingstocks"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No trending stocks found","content":{"application/json":{"example":{"detail":"No trending stocks found."}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/reddit/stocks/v1/trending?from=2026-05-01&to=2026-05-07&limit=5\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/reddit/stocks/v1/trending?from=2026-05-01&to=2026-05-07&limit=5\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/reddit/stocks/v1/trending?from=2026-05-01&to=2026-05-07&limit=5\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/reddit/stocks/v1/trending/sectors":{"get":{"tags":["Reddit Stocks"],"summary":"Trending sectors","description":"Returns the sectors with the strongest aggregated Reddit stock discussion in the selected period, ranked by `buzz_score`.\n\n**Includes:**\n- `buzz_score`: normalized 0-100 activity score used for ranking\n- `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)\n- `mentions`, `unique_tickers`, `subreddit_count`, `total_upvotes`: attributed volume and engagement signals, including inherited thread-context mentions\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals\n- `top_tickers`: up to 5 tickers driving the sector result\n- `trend_history`: independent daily sector buzz scores, oldest to newest; length is max(requested days, 7); the live final value describes today so far and can differ from period `buzz_score`","operationId":"getTrendingSectors","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of results","examples":[10],"default":20,"title":"Limit"},"description":"Maximum number of results"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of items to skip for pagination","examples":[0],"default":0,"title":"Offset"},"description":"Number of items to skip for pagination"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TrendingSector"},"title":"Response Gettrendingsectors"},"example":[{"buzz_score":78.4,"trend":"rising","mentions":4523,"unique_tickers":34,"subreddit_count":15,"sentiment_score":0.28,"bullish_pct":54,"bearish_pct":22,"total_upvotes":128450,"trend_history":[45.2,48.1,52.3,55.0,58.2,61.5,78.4],"top_tickers":["NVDA","AAPL","MSFT","AMD","GOOGL"],"sector":"Technology"}]}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=300"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Gettrendingsectors"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No trending sectors found","content":{"application/json":{"example":{"detail":"No trending sectors found."}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/reddit/stocks/v1/trending/sectors?from=2026-05-01&to=2026-05-07&limit=5\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/reddit/stocks/v1/trending/sectors?from=2026-05-01&to=2026-05-07&limit=5\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/reddit/stocks/v1/trending/sectors?from=2026-05-01&to=2026-05-07&limit=5\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/reddit/stocks/v1/trending/countries":{"get":{"tags":["Reddit Stocks"],"summary":"Trending countries","description":"Returns the countries with the strongest aggregated Reddit stock discussion in the selected period, ranked by `buzz_score`.\n\n**Includes:**\n- `buzz_score`: normalized 0-100 activity score used for ranking\n- `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)\n- `mentions`, `unique_tickers`, `subreddit_count`, `total_upvotes`: attributed volume and engagement signals, including inherited thread-context mentions\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals\n- `top_tickers`: up to 5 tickers driving the country result\n- `trend_history`: independent daily country buzz scores, oldest to newest; length is max(requested days, 7); the live final value describes today so far and can differ from period `buzz_score`","operationId":"getTrendingCountries","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of results","examples":[10],"default":20,"title":"Limit"},"description":"Maximum number of results"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of items to skip for pagination","examples":[0],"default":0,"title":"Offset"},"description":"Number of items to skip for pagination"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TrendingCountry"},"title":"Response Gettrendingcountries"},"example":[{"buzz_score":82.3,"trend":"stable","mentions":8934,"unique_tickers":156,"subreddit_count":18,"sentiment_score":0.21,"bullish_pct":48,"bearish_pct":26,"total_upvotes":245000,"trend_history":[52.1,54.0,56.8,59.2,61.0,60.1,82.3],"top_tickers":["NVDA","TSLA","AAPL","AMD","PLTR"],"country":"United States"}]}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=300"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Gettrendingcountries"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No trending countries found","content":{"application/json":{"example":{"detail":"No trending countries found."}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/reddit/stocks/v1/trending/countries?from=2026-05-01&to=2026-05-07&limit=5\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/reddit/stocks/v1/trending/countries?from=2026-05-01&to=2026-05-07&limit=5\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/reddit/stocks/v1/trending/countries?from=2026-05-01&to=2026-05-07&limit=5\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/reddit/stocks/v1/stock/{ticker}":{"get":{"tags":["Reddit Stocks"],"summary":"Stock sentiment","description":"Returns the Reddit report for one stock ticker.\n\n**Includes:**\n- `buzz_score`: normalized Reddit activity score for the selected period\n- `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)\n- `sentiment_score`, `bullish_pct`, `bearish_pct`, `positive_count`, `negative_count`, `neutral_count`: directional sentiment signals\n- `mentions`, `unique_posts`, `subreddit_count`, `total_upvotes`: attributed volume and engagement signals, including inherited thread-context mentions\n- `daily_trend`: daily Reddit activity and sentiment values\n- `top_mentions`: top explicit Reddit mentions from the selected period, ranked by upvotes\n- `top_subreddits`: top subreddit contributors by attributed mention count\n\nUse raw `/mentions` without `include_inherited` for explicit-only rows.\n\nReturns `200` with `found: false` when the ticker is supported but this service\nhas no qualifying data in the requested window. Returns `404` only when the\nticker is unsupported.","operationId":"getStockSentiment","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","pattern":"^\\$?(?:[A-Za-z0-9]{1,8}[.-][A-Za-z]|[A-Za-z0-9]{0}[A-Za-z][A-Za-z0-9]{0,9}|[A-Za-z0-9]{1}[A-Za-z][A-Za-z0-9]{0,8}|[A-Za-z0-9]{2}[A-Za-z][A-Za-z0-9]{0,7}|[A-Za-z0-9]{3}[A-Za-z][A-Za-z0-9]{0,6}|[A-Za-z0-9]{4}[A-Za-z][A-Za-z0-9]{0,5}|[A-Za-z0-9]{5}[A-Za-z][A-Za-z0-9]{0,4}|[A-Za-z0-9]{6}[A-Za-z][A-Za-z0-9]{0,3}|[A-Za-z0-9]{7}[A-Za-z][A-Za-z0-9]{0,2}|[A-Za-z0-9]{8}[A-Za-z][A-Za-z0-9]{0,1}|[A-Za-z0-9]{9}[A-Za-z][A-Za-z0-9]{0,0}|[0-9]{3,10})$","description":"Stock ticker symbol (e.g., TSLA, aapl, BRK.A, $GME)","title":"Ticker"},"description":"Stock ticker symbol (e.g., TSLA, aapl, BRK.A, $GME)"},{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockSentiment"},"example":{"ticker":"TSLA","company_name":"Tesla, Inc.","found":true,"buzz_score":87.5,"mentions":342,"sentiment_score":0.23,"total_upvotes":15234,"unique_posts":45,"subreddit_count":8,"trend":"rising","bullish_pct":45,"bearish_pct":18,"period_days":7,"top_subreddits":[{"subreddit":"wallstreetbets","mentions":89,"count":89},{"subreddit":"stocks","mentions":67,"count":67}],"daily_trend":[{"date":"2025-12-28","mentions":52,"sentiment_score":0.31,"buzz_score":42.8,"bullish_pct":58,"bearish_pct":19},{"date":"2025-12-27","mentions":48,"sentiment_score":0.18,"buzz_score":38.5,"bullish_pct":46,"bearish_pct":21}],"top_mentions":[{"text_snippet":"TSLA looking strong after...","sentiment_score":0.85,"sentiment_label":"positive","upvotes":1234,"subreddit":"wallstreetbets","created_utc":"2025-12-28T10:30:00Z"}]}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=30"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Getstocksentiment"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Unsupported ticker","content":{"application/json":{"example":{"detail":{"error_code":"unsupported_ticker","message":"Unsupported ticker $XYZ. This ticker is not supported by Adanos v1."}},"schema":{"$ref":"#/components/schemas/UnsupportedAssetError"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/reddit/stocks/v1/stock/TSLA?from=2026-05-01&to=2026-05-07\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/reddit/stocks/v1/stock/TSLA?from=2026-05-01&to=2026-05-07\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/reddit/stocks/v1/stock/TSLA?from=2026-05-01&to=2026-05-07\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/reddit/stocks/v1/market-sentiment":{"get":{"tags":["Reddit Stocks"],"summary":"Market sentiment","description":"Returns one reading for all Reddit stock discussion: overall buzz, sentiment split, activity trend, breadth and the `drivers` behind it, ranked by `buzz_score`.\n\nHere `buzz_score` compares overall Reddit stock activity with its own trailing 90-day baseline:\n- around `50` = normal Reddit market activity\n- higher = more active than usual\n- lower = quieter than usual\n\n`trend` is activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).\n\nUse `sentiment_score`, `bullish_pct` and `bearish_pct` for direction.\n\n`mentions` includes inherited thread-context mentions. Use raw `/mentions` without\n`include_inherited` for explicit-only rows.","operationId":"getRedditMarketSentiment","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedditMarketSentimentResponse"},"example":{"buzz_score":57.4,"trend":"stable","mentions":3992,"unique_posts":418,"subreddit_count":21,"total_upvotes":15234,"active_tickers":1000,"sentiment_score":0.045,"positive_count":1440,"negative_count":998,"neutral_count":1554,"bullish_pct":36,"bearish_pct":25,"trend_history":[49.8,52.1,50.7,55.6,58.3,60.2,57.4],"drivers":[{"ticker":"SPY","mentions":129,"buzz_score":74.1,"sentiment_score":0.009},{"ticker":"GOOGL","mentions":106,"buzz_score":71.8,"sentiment_score":0.029}]}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=300"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Getredditmarketsentiment"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/reddit/stocks/v1/market-sentiment?from=2026-05-01&to=2026-05-07\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/reddit/stocks/v1/market-sentiment?from=2026-05-01&to=2026-05-07\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/reddit/stocks/v1/market-sentiment?from=2026-05-01&to=2026-05-07\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/reddit/stocks/v1/stock/{ticker}/explain":{"get":{"tags":["Reddit Stocks"],"summary":"AI explanation","description":"Returns an AI-generated explanation for why a stock is trending on Reddit, based on recent mention data and sentiment. Explanations are cached for 6 hours.\n\n**Includes:**\n- `explanation`: 1-2 sentence summary of why the stock is trending\n- `cached`: whether this was served from cache\n- `generated_at`: when the explanation was generated\n- `model`: the language model that wrote the explanation","operationId":"getStockExplanation","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","pattern":"^\\$?(?:[A-Za-z0-9]{1,8}[.-][A-Za-z]|[A-Za-z0-9]{0}[A-Za-z][A-Za-z0-9]{0,9}|[A-Za-z0-9]{1}[A-Za-z][A-Za-z0-9]{0,8}|[A-Za-z0-9]{2}[A-Za-z][A-Za-z0-9]{0,7}|[A-Za-z0-9]{3}[A-Za-z][A-Za-z0-9]{0,6}|[A-Za-z0-9]{4}[A-Za-z][A-Za-z0-9]{0,5}|[A-Za-z0-9]{5}[A-Za-z][A-Za-z0-9]{0,4}|[A-Za-z0-9]{6}[A-Za-z][A-Za-z0-9]{0,3}|[A-Za-z0-9]{7}[A-Za-z][A-Za-z0-9]{0,2}|[A-Za-z0-9]{8}[A-Za-z][A-Za-z0-9]{0,1}|[A-Za-z0-9]{9}[A-Za-z][A-Za-z0-9]{0,0}|[0-9]{3,10})$","description":"Stock ticker symbol (e.g., TSLA, aapl, BRK.A, $GME)","title":"Ticker"},"description":"Stock ticker symbol (e.g., TSLA, aapl, BRK.A, $GME)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockExplanationResponse"},"example":{"ticker":"GME","company_name":"Gamestop Corporation - Class A","explanation":"GME is trending due to viral GameStop social media activity and large position posts on r/Superstonk.","cached":true,"generated_at":"2026-01-13T14:30:00+00:00","model":"google/gemma-4-31B-it-turbo"}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=60"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Getstockexplanation"}}}},"503":{"description":"Explanation or database service unavailable","content":{"application/json":{"example":{"detail":"Explanation service temporarily unavailable. Try again later."}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found or no data available for the requested asset/window","content":{"application/json":{"example":{"detail":"No mentions found for $XYZ in the last 7 days."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/reddit/stocks/v1/stock/TSLA/explain\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/reddit/stocks/v1/stock/TSLA/explain\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/reddit/stocks/v1/stock/TSLA/explain\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/reddit/stocks/v1/compare":{"get":{"tags":["Reddit Stocks"],"summary":"Compare stocks","description":"Compare up to 10 stock or ETF tickers side by side over the same UTC calendar-day period.\n\nResults are sorted by `buzz_score` descending and return the same core analytics used by\n`/trending`: `buzz_score`, `trend`, `trend_history`, `mentions`, `unique_posts`,\n`subreddit_count`, `sentiment_score`, `bullish_pct`, `bearish_pct` and `total_upvotes`.\n`trend` is activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).\n\nEach requested ticker gets one row. Tickers without activity in the period, including unsupported ones, return zeroed metrics. Unsupported tickers have no company name; use `/search` to check support.\n\n`mentions` includes inherited thread-context mentions. Use raw `/mentions` without\n`include_inherited` for explicit-only rows.","operationId":"compareStocks","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."},{"name":"tickers","in":"query","required":true,"schema":{"type":"string","description":"Comma-separated list of ticker symbols (e.g., TSLA,NVDA,AMD)","examples":["TSLA,NVDA,AMD"],"title":"Tickers"},"description":"Comma-separated list of ticker symbols (e.g., TSLA,NVDA,AMD)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompareResponse"},"example":{"period_days":7,"stocks":[{"ticker":"TSLA","company_name":"Tesla, Inc.","buzz_score":87.5,"trend":"rising","mentions":342,"unique_posts":45,"subreddit_count":8,"sentiment_score":0.23,"bullish_pct":45,"bearish_pct":18,"total_upvotes":15234,"trend_history":[45.2,52.1,48.7,67.3,72.1,78.4,87.5]},{"ticker":"NVDA","company_name":"NVIDIA Corporation","buzz_score":72.3,"trend":"stable","mentions":189,"unique_posts":31,"subreddit_count":6,"sentiment_score":0.45,"bullish_pct":52,"bearish_pct":17,"total_upvotes":8921,"trend_history":[38.1,40.7,44.9,51.5,57.4,63.0,72.3]}]}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=30"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Comparestocks"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"400":{"description":"Invalid compare item list","content":{"application/json":{"example":{"detail":{"error":"too_many_tickers","message":"Maximum 10 tickers allowed.","max_items":10,"item_name":"ticker"}},"examples":{"too_many_tickers":{"summary":"Too many tickers","value":{"detail":{"error":"too_many_tickers","message":"Maximum 10 tickers allowed.","max_items":10,"item_name":"ticker"}}},"no_valid_tickers":{"summary":"No valid tickers","value":{"detail":{"error":"no_valid_tickers","message":"At least one valid ticker is required.","max_items":10,"item_name":"ticker"}}}},"schema":{"$ref":"#/components/schemas/CompareLimitError"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/reddit/stocks/v1/compare?from=2026-05-01&to=2026-05-07&tickers=TSLA,AAPL,NVDA\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/reddit/stocks/v1/compare?from=2026-05-01&to=2026-05-07&tickers=TSLA,AAPL,NVDA\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/reddit/stocks/v1/compare?from=2026-05-01&to=2026-05-07&tickers=TSLA,AAPL,NVDA\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/reddit/stocks/v1/search":{"get":{"tags":["Reddit Stocks"],"summary":"Search stocks","description":"Search stocks by ticker, company name or alias. Results prioritize match relevance first (exact ticker matches, then prefixes, then name/alias matches) and include a compact summary block for the last 7 UTC calendar days. Summary mentions include inherited thread-context mentions; use raw /mentions without include_inherited for explicit-only rows.","operationId":"searchStocks","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"description":"Search query (minimum 2 non-$ characters after trimming)","examples":["tesla"],"title":"Q"},"description":"Search query (minimum 2 non-$ characters after trimming)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"Maximum number of results to return","examples":[20],"default":20,"title":"Limit"},"description":"Maximum number of results to return"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"},"example":{"query":"tesla","count":1,"period_days":7,"results":[{"ticker":"TSLA","name":"Tesla Inc.","type":"Stock","exchange":"NASDAQ","sector":"Consumer Discretionary","country":"United States","aliases":["Tesla","Elon"],"summary":{"mentions":342,"buzz_score":87.5,"trend":"rising","sentiment_score":0.23,"bearish_pct":18,"bullish_pct":45,"subreddit_count":8,"total_upvotes":15234,"unique_posts":45}}]}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=15"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Invalid search query parameters","content":{"application/json":{"examples":{"fixed_window":{"summary":"Search endpoints use a fixed summary window","value":{"detail":{"error":"Invalid search parameters","message":"Search endpoints use a fixed last-7-UTC-calendar-day summary window.","unsupported_parameters":["days"]}}},"normalized_query":{"summary":"Search query is too short after normalization","value":{"detail":"Search query must contain at least 2 non-$ characters after trimming"}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"string_too_short","loc":["query","q"],"msg":"String should have at least 2 characters","input":"t","ctx":{"min_length":2}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidSearchParametersError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Searchstocks"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/reddit/stocks/v1/search?q=tesla&limit=5\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/reddit/stocks/v1/search?q=tesla&limit=5\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/reddit/stocks/v1/search?q=tesla&limit=5\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/reddit/stocks/v1/stats":{"get":{"tags":["Reddit Stocks"],"summary":"Dataset statistics","description":"Returns high-level Reddit stock dataset coverage metrics for questions like:\n- how many stock mention rows are stored\n- how many distinct tickers currently have Reddit data\n- how many mention rows and distinct tickers are present today (UTC)\n- how many supported tickers exist in the reference universe\n\nToday's counters start at 00:00 UTC and include post, comment and inherited\nthread-context mentions.","operationId":"getStats","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedditStatsResponse"},"example":{"total_mentions":12833,"unique_tickers":65,"mentions_today":342,"unique_tickers_today":21,"supported_tickers":35000}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=300"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"},"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Database temporarily unavailable"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Request deadline exceeded"}}}}},"security":[{"ApiKeyAuth":[]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/reddit/stocks/v1/stats\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/reddit/stocks/v1/stats\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/reddit/stocks/v1/stats\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/reddit/stocks/v1/stock/{ticker}/mentions":{"get":{"tags":["Reddit Stocks"],"summary":"Raw mentions","description":"Returns raw mention rows for a specific stock ticker within the live raw-data retention window.\n**Professional account required.** Free and Hobby accounts cannot use this endpoint.\n\n**Use this endpoint when you need:**\n- post/comment-level snippets\n- original timestamps\n- inherited-context filtering\n\n**Notes:**\n- Use `from` and `to` for explicit UTC date windows\n- Results are ordered newest first and support deterministic `offset` + `limit` pagination\n- `include_inherited=false` by default\n- empty result sets return `200` with `results=[]`","operationId":"getStockRawMentions","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","pattern":"^\\$?(?:[A-Za-z0-9]{1,8}[.-][A-Za-z]|[A-Za-z0-9]{0}[A-Za-z][A-Za-z0-9]{0,9}|[A-Za-z0-9]{1}[A-Za-z][A-Za-z0-9]{0,8}|[A-Za-z0-9]{2}[A-Za-z][A-Za-z0-9]{0,7}|[A-Za-z0-9]{3}[A-Za-z][A-Za-z0-9]{0,6}|[A-Za-z0-9]{4}[A-Za-z][A-Za-z0-9]{0,5}|[A-Za-z0-9]{5}[A-Za-z][A-Za-z0-9]{0,4}|[A-Za-z0-9]{6}[A-Za-z][A-Za-z0-9]{0,3}|[A-Za-z0-9]{7}[A-Za-z][A-Za-z0-9]{0,2}|[A-Za-z0-9]{8}[A-Za-z][A-Za-z0-9]{0,1}|[A-Za-z0-9]{9}[A-Za-z][A-Za-z0-9]{0,0}|[0-9]{3,10})$","description":"Stock ticker symbol (e.g., TSLA, aapl, BRK.A, $GME)","title":"Ticker"},"description":"Stock ticker symbol (e.g., TSLA, aapl, BRK.A, $GME)"},{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of raw mention rows to return","examples":[50],"default":50,"title":"Limit"},"description":"Maximum number of raw mention rows to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of raw mention rows to skip for offset-based pagination.","examples":[0],"default":0,"title":"Offset"},"description":"Number of raw mention rows to skip for offset-based pagination."},{"name":"include_inherited","in":"query","required":false,"schema":{"type":"boolean","description":"Include thread-context inherited mentions in addition to direct ticker mentions","default":false,"title":"Include Inherited"},"description":"Include thread-context inherited mentions in addition to direct ticker mentions"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RedditRawMentionsResponse"},"example":{"ticker":"TSLA","period_days":7,"count":1,"results":[{"post_id":"abc123","comment_id":"def456","subreddit":"wallstreetbets","author":"user123","text_snippet":"TSLA looks strong into earnings...","created_utc":"2026-03-20T18:42:10Z","upvotes":381,"sentiment_score":0.62,"sentiment_label":"positive","is_inherited":false}]}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=60"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Getstockrawmentions"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/reddit/stocks/v1/stock/TSLA/mentions?from=2026-05-01&to=2026-05-07&limit=5\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/reddit/stocks/v1/stock/TSLA/mentions?from=2026-05-01&to=2026-05-07&limit=5\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/reddit/stocks/v1/stock/TSLA/mentions?from=2026-05-01&to=2026-05-07&limit=5\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/reddit/crypto/v1/trending":{"get":{"tags":["Reddit Crypto"],"summary":"Trending tokens","description":"Returns the crypto assets with the strongest Reddit discussion activity in the selected period, ranked by `buzz_score`.\n\n**Includes:**\n- `buzz_score`: normalized 0-100 activity score used for ranking\n- `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals\n- `mentions`, `unique_posts`, `subreddit_count`, `total_upvotes`: attributed volume and engagement signals, including inherited thread-context mentions\n- `trend_history`: independent UTC-day buzz scores, oldest to newest; minimum 7 values; the live final value describes today so far and can differ from the selected-period `buzz_score`; missing days are `0.0`","operationId":"getRedditCryptoTrending","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum tokens to return","default":20,"title":"Limit"},"description":"Maximum tokens to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pagination offset","default":0,"title":"Offset"},"description":"Pagination offset"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CryptoTrendingToken"},"title":"Response Getredditcryptotrending"},"example":[{"symbol":"BTC","name":"Bitcoin","buzz_score":78.1,"trend":"rising","mentions":423,"unique_posts":97,"subreddit_count":12,"sentiment_score":0.31,"bullish_pct":47,"bearish_pct":18,"total_upvotes":15620,"trend_history":[42.3,46.8,51.2,58.9,64.0,71.4,78.1]}]}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=30"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Getredditcryptotrending"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No trending crypto tokens found","content":{"application/json":{"example":{"detail":"No trending crypto tokens found."}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/reddit/crypto/v1/trending?from=2026-05-01&to=2026-05-07&limit=5\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/reddit/crypto/v1/trending?from=2026-05-01&to=2026-05-07&limit=5\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/reddit/crypto/v1/trending?from=2026-05-01&to=2026-05-07&limit=5\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/reddit/crypto/v1/token/{symbol}":{"get":{"tags":["Reddit Crypto"],"summary":"Token sentiment","description":"Returns the Reddit report for one crypto symbol.\n\n**Includes:**\n- `buzz_score`: normalized Reddit activity score for the selected period\n- `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals\n- `mentions`, `unique_posts`, `subreddit_count`, `total_upvotes`: attributed volume and engagement signals, including inherited thread-context mentions\n- `daily_trend`: daily Reddit activity and sentiment values\n- `top_mentions`: representative high-engagement Reddit posts or comments from the selected period\n\nReturns `200` with `found: false` when the symbol is supported but this service\nhas no qualifying data in the requested window. Returns `404` only when the\nsymbol is unsupported.","operationId":"getRedditCryptoToken","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string","pattern":"^\\$?[A-Za-z0-9]{1,20}$","description":"Crypto symbol (e.g., BTC, $ETH, SOL)","title":"Symbol"},"description":"Crypto symbol (e.g., BTC, $ETH, SOL)"},{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CryptoTokenSentiment"},"example":{"symbol":"ETH","name":"Ethereum","found":true,"buzz_score":72.4,"mentions":318,"sentiment_score":0.27,"total_upvotes":10422,"unique_posts":73,"subreddit_count":9,"trend":"stable","bullish_pct":43,"bearish_pct":19,"period_days":7,"top_subreddits":[{"subreddit":"ethtrader","mentions":91,"count":91},{"subreddit":"cryptocurrency","mentions":84,"count":84}],"daily_trend":[{"date":"2026-02-24","mentions":48,"sentiment_score":0.22,"buzz_score":56.4,"bullish_pct":58,"bearish_pct":21},{"date":"2026-02-23","mentions":42,"sentiment_score":0.19,"buzz_score":51.7,"bullish_pct":52,"bearish_pct":24}],"top_mentions":[{"text_snippet":"ETH setup still looks strong into the next catalyst.","sentiment_score":0.74,"sentiment_label":"positive","upvotes":1200,"subreddit":"ethtrader","created_utc":"2026-02-24T09:15:00Z"}]}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=30"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Getredditcryptotoken"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Unsupported crypto symbol","content":{"application/json":{"example":{"detail":{"error_code":"unsupported_symbol","message":"Unsupported symbol ZZZ. This symbol is not supported by Adanos v1."}},"schema":{"$ref":"#/components/schemas/UnsupportedAssetError"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/reddit/crypto/v1/token/BTC?from=2026-05-01&to=2026-05-07\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/reddit/crypto/v1/token/BTC?from=2026-05-01&to=2026-05-07\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/reddit/crypto/v1/token/BTC?from=2026-05-01&to=2026-05-07\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/reddit/crypto/v1/market-sentiment":{"get":{"tags":["Reddit Crypto"],"summary":"Market sentiment","description":"Returns one reading for all Reddit crypto discussion: overall buzz, sentiment split, activity trend, breadth and the `drivers` behind it, ranked by `buzz_score`.\n\nHere `buzz_score` compares overall Reddit crypto discussion with its own trailing 90-day baseline:\n- around `50` = normal Reddit crypto activity\n- higher = more active than usual\n- lower = quieter than usual\n\n`trend` is activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).\n\nUse `sentiment_score`, `bullish_pct` and `bearish_pct` for direction.\n\n`mentions` includes inherited thread-context mentions. Use raw `/mentions` without\n`include_inherited` for explicit-only rows.","operationId":"getRedditCryptoMarketSentiment","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CryptoMarketSentimentResponse"},"example":{"buzz_score":52.4,"trend":"stable","mentions":5412,"unique_posts":1184,"subreddit_count":37,"total_upvotes":41290,"active_tickers":89,"sentiment_score":0.117,"positive_count":2101,"negative_count":1318,"neutral_count":1993,"bullish_pct":39,"bearish_pct":24,"trend_history":[47.1,49.3,50.4,52.2,51.8,53.0,52.4],"drivers":[{"symbol":"BTC","mentions":423,"buzz_score":78.1,"sentiment_score":0.31},{"symbol":"ETH","mentions":318,"buzz_score":72.4,"sentiment_score":0.27}]}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=300"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Getredditcryptomarketsentiment"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/reddit/crypto/v1/market-sentiment?from=2026-05-01&to=2026-05-07\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/reddit/crypto/v1/market-sentiment?from=2026-05-01&to=2026-05-07\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/reddit/crypto/v1/market-sentiment?from=2026-05-01&to=2026-05-07\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/reddit/crypto/v1/compare":{"get":{"tags":["Reddit Crypto"],"summary":"Compare tokens","description":"Compare up to 10 crypto symbols side by side over the same UTC calendar-day period.\n\nUse it for watchlists: one compact row per symbol.\nResults are sorted by `buzz_score` descending and include attributed `mentions`, `trend`, `trend_history`, `unique_posts`, `subreddit_count`, `sentiment_score`, `bullish_pct`, `bearish_pct` and `total_upvotes`.\n`trend` is activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).\nEach requested symbol gets one row. Symbols without activity in the period, including unsupported ones, return zeroed metrics. Unsupported symbols have no name; use `/search` to check support.","operationId":"compareRedditCryptoTokens","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."},{"name":"symbols","in":"query","required":true,"schema":{"type":"string","description":"Comma-separated symbols (e.g., BTC,ETH,SOL)","title":"Symbols"},"description":"Comma-separated symbols (e.g., BTC,ETH,SOL)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CryptoCompareResponse"},"example":{"period_days":7,"tokens":[{"symbol":"BTC","name":"Bitcoin","buzz_score":78.1,"trend":"rising","mentions":423,"unique_posts":97,"subreddit_count":12,"sentiment_score":0.31,"bullish_pct":47,"bearish_pct":18,"total_upvotes":15620,"trend_history":[42.3,46.8,51.2,58.9,64.0,71.4,78.1]},{"symbol":"ETH","name":"Ethereum","buzz_score":72.4,"trend":"stable","mentions":318,"unique_posts":73,"subreddit_count":9,"sentiment_score":0.27,"bullish_pct":43,"bearish_pct":19,"total_upvotes":10422,"trend_history":[36.2,41.4,46.7,53.1,60.2,66.5,72.4]}]}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=30"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Compareredditcryptotokens"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"400":{"description":"Invalid compare item list","content":{"application/json":{"example":{"detail":{"error":"too_many_symbols","message":"Maximum 10 symbols allowed.","max_items":10,"item_name":"symbol"}},"examples":{"too_many_symbols":{"summary":"Too many symbols","value":{"detail":{"error":"too_many_symbols","message":"Maximum 10 symbols allowed.","max_items":10,"item_name":"symbol"}}},"no_valid_symbols":{"summary":"No valid symbols","value":{"detail":{"error":"no_valid_symbols","message":"At least one valid symbol is required.","max_items":10,"item_name":"symbol"}}}},"schema":{"$ref":"#/components/schemas/CompareLimitError"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/reddit/crypto/v1/compare?from=2026-05-01&to=2026-05-07&symbols=BTC,ETH,SOL\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/reddit/crypto/v1/compare?from=2026-05-01&to=2026-05-07&symbols=BTC,ETH,SOL\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/reddit/crypto/v1/compare?from=2026-05-01&to=2026-05-07&symbols=BTC,ETH,SOL\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/reddit/crypto/v1/search":{"get":{"tags":["Reddit Crypto"],"summary":"Search tokens","description":"Search known crypto assets by symbol, name or alias. Results prioritize exact symbol matches first, then prefixes, then name/alias matches and include a compact `summary` block for the last 7 UTC calendar days.\nSummary `mentions` includes inherited thread-context mentions.","operationId":"searchRedditCrypto","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"description":"Search query (minimum 2 non-$ characters after trimming)","title":"Q"},"description":"Search query (minimum 2 non-$ characters after trimming)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"Maximum number of results to return","examples":[20],"default":20,"title":"Limit"},"description":"Maximum number of results to return"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CryptoSearchResponse"},"example":{"query":"solana","count":1,"period_days":7,"results":[{"symbol":"SOL","name":"Solana","market_cap_rank":6,"market_cap_usd":71234567890.12,"aliases":["Sol"],"summary":{"mentions":287,"buzz_score":72.4,"trend":"stable","sentiment_score":0.27,"bearish_pct":19,"bullish_pct":43,"subreddit_count":9,"total_upvotes":10422,"unique_posts":73}}]}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=15"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Invalid search query parameters","content":{"application/json":{"examples":{"fixed_window":{"summary":"Search endpoints use a fixed summary window","value":{"detail":{"error":"Invalid search parameters","message":"Search endpoints use a fixed last-7-UTC-calendar-day summary window.","unsupported_parameters":["days"]}}},"normalized_query":{"summary":"Search query is too short after normalization","value":{"detail":"Search query must contain at least 2 non-$ characters after trimming"}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"string_too_short","loc":["query","q"],"msg":"String should have at least 2 characters","input":"t","ctx":{"min_length":2}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidSearchParametersError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Searchredditcrypto"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/reddit/crypto/v1/search?q=bitcoin&limit=5\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/reddit/crypto/v1/search?q=bitcoin&limit=5\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/reddit/crypto/v1/search?q=bitcoin&limit=5\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/reddit/crypto/v1/stats":{"get":{"tags":["Reddit Crypto"],"summary":"Dataset statistics","description":"Returns high-level Reddit Crypto dataset coverage metrics.\n\nIncludes:\n- total mention rows stored\n- number of distinct tracked symbols with data, exposed as `unique_tokens`\n- today's UTC mention and distinct symbol counts, exposed as `unique_tokens_today`\n- number of supported symbols, exposed as `supported_tokens`","operationId":"getRedditCryptoStats","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CryptoStatsResponse"},"example":{"total_mentions":18352,"unique_tokens":142,"mentions_today":287,"unique_tokens_today":35,"supported_tokens":500}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=300"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"},"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Database temporarily unavailable"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Request deadline exceeded"}}}}},"security":[{"ApiKeyAuth":[]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/reddit/crypto/v1/stats\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/reddit/crypto/v1/stats\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/reddit/crypto/v1/stats\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/reddit/crypto/v1/token/{symbol}/mentions":{"get":{"tags":["Reddit Crypto"],"summary":"Raw mentions","description":"Returns raw Reddit mention rows for a specific crypto symbol within the live raw-data retention window.\n**Professional account required.** Free and Hobby accounts cannot use this endpoint.\n\n**Use this endpoint when you need:**\n- post/comment-level snippets\n- original timestamps\n- inherited-context filtering\n\n**Notes:**\n- Use `from` and `to` for explicit UTC date windows\n- Results are ordered newest first and support deterministic `offset` + `limit` pagination\n- `include_inherited=false` by default\n- empty result sets return `200` with `results=[]`","operationId":"getRedditCryptoTokenMentions","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string","pattern":"^\\$?[A-Za-z0-9]{1,20}$","description":"Crypto symbol (e.g., BTC, $ETH, SOL)","title":"Symbol"},"description":"Crypto symbol (e.g., BTC, $ETH, SOL)"},{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of raw mentions to return","default":50,"title":"Limit"},"description":"Maximum number of raw mentions to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of raw mention rows to skip for offset-based pagination.","default":0,"title":"Offset"},"description":"Number of raw mention rows to skip for offset-based pagination."},{"name":"include_inherited","in":"query","required":false,"schema":{"type":"boolean","description":"Include inherited thread-context mentions in addition to direct symbol matches","default":false,"title":"Include Inherited"},"description":"Include inherited thread-context mentions in addition to direct symbol matches"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CryptoRawMentionsResponse"},"example":{"symbol":"BTC","period_days":7,"count":1,"results":[{"post_id":"abc123","comment_id":"def456","subreddit":"cryptocurrency","author":"user123","text_snippet":"BTC still looks strong above this range...","created_utc":"2026-03-20T18:42:10Z","upvotes":381,"sentiment_score":0.62,"sentiment_label":"positive","is_inherited":false}]}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=60"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Getredditcryptotokenmentions"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/reddit/crypto/v1/token/BTC/mentions?from=2026-05-01&to=2026-05-07&limit=5\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/reddit/crypto/v1/token/BTC/mentions?from=2026-05-01&to=2026-05-07&limit=5\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/reddit/crypto/v1/token/BTC/mentions?from=2026-05-01&to=2026-05-07&limit=5\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/x/stocks/v1/trending":{"get":{"tags":["X/Twitter Stocks"],"summary":"Trending stocks","description":"Returns the stocks with the strongest X/Twitter discussion activity in the selected period, ranked by `buzz_score`.\n\n**Includes:**\n- `buzz_score`: normalized 0-100 activity score used for ranking\n- `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, likes and author breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals\n- `mentions`, `unique_tweets`, `total_upvotes`: volume and engagement signals\n- `trend_history`: independent UTC-day buzz scores, oldest to newest; minimum 7 values; the live final value describes today so far and can differ from the selected-period `buzz_score`; missing days are `0.0`","operationId":"getXTrendingStocks","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum stocks to return","examples":[20],"default":20,"title":"Limit"},"description":"Maximum stocks to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of items to skip for pagination","examples":[0],"default":0,"title":"Offset"},"description":"Number of items to skip for pagination"},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["stock","etf","all"],"type":"string"},{"type":"null"}],"description":"Filter by asset type. Omit or use 'all' for all assets.","examples":["stock"],"title":"Type"},"description":"Filter by asset type. Omit or use 'all' for all assets."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/XTrendingStock"},"title":"Response Getxtrendingstocks"},"example":[{"ticker":"TSLA","company_name":"Tesla, Inc.","buzz_score":72.5,"trend":"rising","mentions":156,"sentiment_score":0.35,"bullish_pct":45,"bearish_pct":12,"total_upvotes":2847,"unique_tweets":42,"trend_history":[45.2,48.1,52.3,55.0,58.2,61.5,64.8]}]}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=30"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Getxtrendingstocks"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/x/stocks/v1/trending?from=2026-05-01&to=2026-05-07&limit=5\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/x/stocks/v1/trending?from=2026-05-01&to=2026-05-07&limit=5\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/x/stocks/v1/trending?from=2026-05-01&to=2026-05-07&limit=5\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/x/stocks/v1/trending/sectors":{"get":{"tags":["X/Twitter Stocks"],"summary":"Trending sectors","description":"Returns the sectors with the strongest aggregated X/Twitter stock discussion in the selected period, ranked by `buzz_score`.\n\n**Includes:**\n- `buzz_score`: normalized 0-100 activity score used for ranking\n- `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, likes and author breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)\n- `mentions`, `unique_tickers`, `total_upvotes`: volume and engagement signals\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals\n- `top_tickers`: up to 5 tickers driving the sector result\n- `trend_history`: independent daily sector buzz scores, oldest to newest; length is max(requested days, 7); the live final value describes today so far and can differ from period `buzz_score`","operationId":"getXTrendingSectors","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of results","examples":[10],"default":20,"title":"Limit"},"description":"Maximum number of results"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of items to skip for pagination","examples":[0],"default":0,"title":"Offset"},"description":"Number of items to skip for pagination"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/XTrendingSector"},"title":"Response Getxtrendingsectors"},"example":[{"buzz_score":78.4,"trend":"rising","mentions":4523,"unique_tickers":34,"unique_authors":156,"sentiment_score":0.28,"bullish_pct":54,"bearish_pct":22,"total_upvotes":128450,"trend_history":[45.2,48.1,52.3,55.0,58.2,61.5,78.4],"top_tickers":["NVDA","AAPL","MSFT","AMD","GOOGL"],"sector":"Technology"}]}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=300"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Getxtrendingsectors"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/x/stocks/v1/trending/sectors?from=2026-05-01&to=2026-05-07&limit=5\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/x/stocks/v1/trending/sectors?from=2026-05-01&to=2026-05-07&limit=5\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/x/stocks/v1/trending/sectors?from=2026-05-01&to=2026-05-07&limit=5\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/x/stocks/v1/trending/countries":{"get":{"tags":["X/Twitter Stocks"],"summary":"Trending countries","description":"Returns the countries with the strongest aggregated X/Twitter stock discussion in the selected period, ranked by `buzz_score`.\n\n**Includes:**\n- `buzz_score`: normalized 0-100 activity score used for ranking\n- `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, likes and author breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)\n- `mentions`, `unique_tickers`, `total_upvotes`: volume and engagement signals\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals\n- `top_tickers`: up to 5 tickers driving the country result\n- `trend_history`: independent daily country buzz scores, oldest to newest; length is max(requested days, 7); the live final value describes today so far and can differ from period `buzz_score`","operationId":"getXTrendingCountries","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of results","examples":[10],"default":20,"title":"Limit"},"description":"Maximum number of results"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of items to skip for pagination","examples":[0],"default":0,"title":"Offset"},"description":"Number of items to skip for pagination"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/XTrendingCountry"},"title":"Response Getxtrendingcountries"},"example":[{"buzz_score":82.3,"trend":"stable","mentions":8934,"unique_tickers":156,"unique_authors":423,"sentiment_score":0.21,"bullish_pct":48,"bearish_pct":26,"total_upvotes":245000,"trend_history":[52.1,54.0,56.8,59.2,61.0,60.1,82.3],"top_tickers":["NVDA","TSLA","AAPL","AMD","PLTR"],"country":"United States"}]}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=300"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Getxtrendingcountries"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/x/stocks/v1/trending/countries?from=2026-05-01&to=2026-05-07&limit=5\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/x/stocks/v1/trending/countries?from=2026-05-01&to=2026-05-07&limit=5\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/x/stocks/v1/trending/countries?from=2026-05-01&to=2026-05-07&limit=5\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/x/stocks/v1/stock/{ticker}":{"get":{"tags":["X/Twitter Stocks"],"summary":"Stock sentiment","description":"Returns the X/Twitter report for one stock ticker.\n\n**Includes:**\n- `buzz_score`: normalized X/Twitter activity score for the selected period\n- `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, likes and author breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals\n- `mentions`, `unique_tweets`, `total_upvotes`: volume and engagement signals\n- `daily_trend`: daily X/Twitter activity and sentiment values\n- `top_tweets`: representative high-engagement tweets from the selected period\n\nReturns `200` with `found: false` when the ticker is supported but this service\nhas no qualifying data in the requested window. Returns `404` only when the\nticker is unsupported.","operationId":"getXStockSentiment","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","pattern":"^\\$?(?:[A-Za-z0-9]{1,8}[.-][A-Za-z]|[A-Za-z0-9]{0}[A-Za-z][A-Za-z0-9]{0,9}|[A-Za-z0-9]{1}[A-Za-z][A-Za-z0-9]{0,8}|[A-Za-z0-9]{2}[A-Za-z][A-Za-z0-9]{0,7}|[A-Za-z0-9]{3}[A-Za-z][A-Za-z0-9]{0,6}|[A-Za-z0-9]{4}[A-Za-z][A-Za-z0-9]{0,5}|[A-Za-z0-9]{5}[A-Za-z][A-Za-z0-9]{0,4}|[A-Za-z0-9]{6}[A-Za-z][A-Za-z0-9]{0,3}|[A-Za-z0-9]{7}[A-Za-z][A-Za-z0-9]{0,2}|[A-Za-z0-9]{8}[A-Za-z][A-Za-z0-9]{0,1}|[A-Za-z0-9]{9}[A-Za-z][A-Za-z0-9]{0,0}|[0-9]{3,10})$","description":"Stock ticker symbol (e.g., TSLA, $AAPL, BRK.A)","examples":["TSLA"],"title":"Ticker"},"description":"Stock ticker symbol (e.g., TSLA, $AAPL, BRK.A)"},{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XStockDetailResponse"},"example":{"ticker":"TSLA","company_name":"Tesla, Inc.","found":true,"buzz_score":72.5,"mentions":156,"sentiment_score":0.35,"total_upvotes":2847,"unique_tweets":42,"trend":"rising","bullish_pct":45,"bearish_pct":12,"period_days":7,"daily_trend":[{"date":"2025-12-28","mentions":42,"sentiment_score":0.15,"buzz_score":52.3,"bullish_pct":60,"bearish_pct":25},{"date":"2025-12-27","mentions":38,"sentiment_score":0.22,"buzz_score":48.1,"bullish_pct":55,"bearish_pct":18}],"top_tweets":[{"text_snippet":"$TSLA breaking out! 🚀","sentiment_score":0.85,"sentiment_label":"positive","likes":1247,"retweets":89,"views":52340,"author":"stockguru","created_at":"2025-12-28T14:32:00Z"}],"top_authors":[{"author":"stockguru","mentions":24,"sentiment_score":0.41,"buzz_score":61.8,"count":24}]}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=30"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Getxstocksentiment"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Unsupported ticker","content":{"application/json":{"example":{"detail":{"error_code":"unsupported_ticker","message":"Unsupported ticker $XYZ. This ticker is not supported by Adanos v1."}},"schema":{"$ref":"#/components/schemas/UnsupportedAssetError"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/x/stocks/v1/stock/TSLA?from=2026-05-01&to=2026-05-07\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/x/stocks/v1/stock/TSLA?from=2026-05-01&to=2026-05-07\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/x/stocks/v1/stock/TSLA?from=2026-05-01&to=2026-05-07\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/x/stocks/v1/market-sentiment":{"get":{"tags":["X/Twitter Stocks"],"summary":"Market sentiment","description":"Returns one reading for all X/Twitter stock discussion: overall buzz, sentiment split, activity trend, breadth and the `drivers` behind it, ranked by `buzz_score`.\n\nHere `buzz_score` compares overall X stock discussion with its own trailing 90-day baseline:\n- around `50` = normal X market activity\n- higher = more active than usual\n- lower = quieter than usual\n\n`trend` is activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, likes and author breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).\n\nUse `sentiment_score`, `bullish_pct` and `bearish_pct` for direction.","operationId":"getXMarketSentiment","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XMarketSentimentResponse"},"example":{"buzz_score":56.2,"trend":"rising","mentions":2847,"unique_tweets":913,"unique_authors":604,"total_upvotes":28471,"active_tickers":442,"sentiment_score":0.081,"positive_count":1198,"negative_count":741,"neutral_count":908,"bullish_pct":42,"bearish_pct":26,"trend_history":[48.9,50.7,52.6,54.4,57.1,58.3,56.2],"drivers":[{"ticker":"TSLA","mentions":156,"buzz_score":72.5,"sentiment_score":0.35},{"ticker":"NVDA","mentions":141,"buzz_score":70.8,"sentiment_score":0.27}]}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=300"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Getxmarketsentiment"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/x/stocks/v1/market-sentiment?from=2026-05-01&to=2026-05-07\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/x/stocks/v1/market-sentiment?from=2026-05-01&to=2026-05-07\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/x/stocks/v1/market-sentiment?from=2026-05-01&to=2026-05-07\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/x/stocks/v1/stock/{ticker}/explain":{"get":{"tags":["X/Twitter Stocks"],"summary":"AI explanation","description":"Returns an AI-generated explanation for why a stock is trending on X/Twitter, anchored to tweet evidence with other platforms used only as cross-check context.\n\n**Includes:**\n- `explanation`: 1-2 sentence summary of why the stock is trending\n- `cached`: whether this was served from cache\n- `generated_at`: when the explanation was generated\n- `model`: the language model that wrote the explanation","operationId":"getXStockExplanation","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","pattern":"^\\$?(?:[A-Za-z0-9]{1,8}[.-][A-Za-z]|[A-Za-z0-9]{0}[A-Za-z][A-Za-z0-9]{0,9}|[A-Za-z0-9]{1}[A-Za-z][A-Za-z0-9]{0,8}|[A-Za-z0-9]{2}[A-Za-z][A-Za-z0-9]{0,7}|[A-Za-z0-9]{3}[A-Za-z][A-Za-z0-9]{0,6}|[A-Za-z0-9]{4}[A-Za-z][A-Za-z0-9]{0,5}|[A-Za-z0-9]{5}[A-Za-z][A-Za-z0-9]{0,4}|[A-Za-z0-9]{6}[A-Za-z][A-Za-z0-9]{0,3}|[A-Za-z0-9]{7}[A-Za-z][A-Za-z0-9]{0,2}|[A-Za-z0-9]{8}[A-Za-z][A-Za-z0-9]{0,1}|[A-Za-z0-9]{9}[A-Za-z][A-Za-z0-9]{0,0}|[0-9]{3,10})$","description":"Stock ticker symbol (e.g., TSLA, aapl, BRK.A, $GME)","title":"Ticker"},"description":"Stock ticker symbol (e.g., TSLA, aapl, BRK.A, $GME)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockExplanationResponse"},"example":{"ticker":"GME","company_name":"Gamestop Corporation - Class A","explanation":"GME is trending due to viral GameStop social media activity and large position posts on r/Superstonk.","cached":true,"generated_at":"2026-01-13T14:30:00+00:00","model":"google/gemma-4-31B-it-turbo"}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=60"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Getxstockexplanation"}}}},"503":{"description":"Explanation or database service unavailable","content":{"application/json":{"example":{"detail":"Explanation service temporarily unavailable. Try again later."}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found or no data available for the requested asset/window","content":{"application/json":{"example":{"detail":"No mentions found for $XYZ in the last 7 days."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/x/stocks/v1/stock/TSLA/explain\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/x/stocks/v1/stock/TSLA/explain\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/x/stocks/v1/stock/TSLA/explain\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/x/stocks/v1/compare":{"get":{"tags":["X/Twitter Stocks"],"summary":"Compare stocks","description":"Compare up to 10 stocks side by side using X/Twitter metrics over the same UTC calendar-day period.\n\nUse it for watchlists: one compact row per ticker.\nResults are sorted by `buzz_score` descending and include `trend`, `trend_history`, `mentions`, `unique_tweets`, `sentiment_score`, `bullish_pct`, `bearish_pct` and `total_upvotes`.\n`trend` is activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, likes and author breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).\nEach requested ticker gets one row. Tickers without activity in the period, including unsupported ones, return zeroed metrics. Unsupported tickers have no company name; use `/search` to check support.","operationId":"compareXStocks","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."},{"name":"tickers","in":"query","required":true,"schema":{"type":"string","description":"Comma-separated list of ticker symbols (e.g., TSLA,NVDA,AMD)","examples":["TSLA,NVDA,AMD"],"title":"Tickers"},"description":"Comma-separated list of ticker symbols (e.g., TSLA,NVDA,AMD)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XCompareResponse"},"example":{"period_days":7,"stocks":[{"ticker":"TSLA","company_name":"Tesla, Inc.","buzz_score":72.5,"trend":"rising","mentions":156,"unique_tweets":42,"sentiment_score":0.35,"bullish_pct":45,"bearish_pct":12,"total_upvotes":2847,"trend_history":[45.2,48.1,52.3,55.0,58.2,61.5,72.5]}]}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=30"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Comparexstocks"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"400":{"description":"Invalid compare item list","content":{"application/json":{"example":{"detail":{"error":"too_many_tickers","message":"Maximum 10 tickers allowed.","max_items":10,"item_name":"ticker"}},"examples":{"too_many_tickers":{"summary":"Too many tickers","value":{"detail":{"error":"too_many_tickers","message":"Maximum 10 tickers allowed.","max_items":10,"item_name":"ticker"}}},"no_valid_tickers":{"summary":"No valid tickers","value":{"detail":{"error":"no_valid_tickers","message":"At least one valid ticker is required.","max_items":10,"item_name":"ticker"}}}},"schema":{"$ref":"#/components/schemas/CompareLimitError"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/x/stocks/v1/compare?from=2026-05-01&to=2026-05-07&tickers=TSLA,AAPL,NVDA\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/x/stocks/v1/compare?from=2026-05-01&to=2026-05-07&tickers=TSLA,AAPL,NVDA\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/x/stocks/v1/compare?from=2026-05-01&to=2026-05-07&tickers=TSLA,AAPL,NVDA\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/x/stocks/v1/search":{"get":{"tags":["X/Twitter Stocks"],"summary":"Search stocks","description":"Search stocks by ticker, company name or alias in the X/Twitter universe. Results prioritize exact ticker matches first, then prefixes, then name/alias matches and include a compact `summary` block for the last 7 UTC calendar days.","operationId":"searchXStocks","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"description":"Search query (minimum 2 non-$ characters after trimming)","examples":["tesla"],"title":"Q"},"description":"Search query (minimum 2 non-$ characters after trimming)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"Maximum number of results to return","examples":[20],"default":20,"title":"Limit"},"description":"Maximum number of results to return"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XSearchResponse"},"example":{"query":"tesla","count":1,"period_days":7,"results":[{"ticker":"TSLA","name":"Tesla Inc.","type":"Stock","exchange":"NASDAQ","sector":"Consumer Discretionary","country":"United States","aliases":["Tesla","Elon"],"summary":{"mentions":156,"buzz_score":72.5,"trend":"rising","sentiment_score":0.35}}]}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=15"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Invalid search query parameters","content":{"application/json":{"examples":{"fixed_window":{"summary":"Search endpoints use a fixed summary window","value":{"detail":{"error":"Invalid search parameters","message":"Search endpoints use a fixed last-7-UTC-calendar-day summary window.","unsupported_parameters":["days"]}}},"normalized_query":{"summary":"Search query is too short after normalization","value":{"detail":"Search query must contain at least 2 non-$ characters after trimming"}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"string_too_short","loc":["query","q"],"msg":"String should have at least 2 characters","input":"t","ctx":{"min_length":2}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidSearchParametersError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Searchxstocks"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/x/stocks/v1/search?q=tesla&limit=5\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/x/stocks/v1/search?q=tesla&limit=5\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/x/stocks/v1/search?q=tesla&limit=5\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/x/stocks/v1/stats":{"get":{"tags":["X/Twitter Stocks"],"summary":"Dataset statistics","description":"Returns high-level coverage and freshness metrics for the X/Twitter dataset.\n\nIncludes:\n- total X mentions in the database\n- number of unique tickers with X mentions\n- today's UTC X mention and distinct ticker counts\n- supported ticker count from the reference universe","operationId":"getXStats","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XStatsResponse"},"example":{"total_mentions":935,"unique_tickers":100,"mentions_today":42,"unique_tickers_today":12,"supported_tickers":35000}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=300"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"},"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Database temporarily unavailable"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Request deadline exceeded"}}}}},"security":[{"ApiKeyAuth":[]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/x/stocks/v1/stats\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/x/stocks/v1/stats\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/x/stocks/v1/stats\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/x/stocks/v1/stock/{ticker}/mentions":{"get":{"tags":["X/Twitter Stocks"],"summary":"Raw mentions","description":"Returns raw tweet rows for a specific ticker within the live raw-data retention window.\n**Professional account required.** Free and Hobby accounts cannot use this endpoint.\n\n**Use this endpoint when you need:**\n- tweet-level snippets\n- original timestamps\n- engagement counters on the raw rows\n\n**Notes:**\n- Use `from` and `to` for explicit UTC date windows\n- Results are ordered newest first and support deterministic `offset` + `limit` pagination\n- empty result sets return `200` with `results=[]`","operationId":"getXStockRawMentions","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","pattern":"^\\$?(?:[A-Za-z0-9]{1,8}[.-][A-Za-z]|[A-Za-z0-9]{0}[A-Za-z][A-Za-z0-9]{0,9}|[A-Za-z0-9]{1}[A-Za-z][A-Za-z0-9]{0,8}|[A-Za-z0-9]{2}[A-Za-z][A-Za-z0-9]{0,7}|[A-Za-z0-9]{3}[A-Za-z][A-Za-z0-9]{0,6}|[A-Za-z0-9]{4}[A-Za-z][A-Za-z0-9]{0,5}|[A-Za-z0-9]{5}[A-Za-z][A-Za-z0-9]{0,4}|[A-Za-z0-9]{6}[A-Za-z][A-Za-z0-9]{0,3}|[A-Za-z0-9]{7}[A-Za-z][A-Za-z0-9]{0,2}|[A-Za-z0-9]{8}[A-Za-z][A-Za-z0-9]{0,1}|[A-Za-z0-9]{9}[A-Za-z][A-Za-z0-9]{0,0}|[0-9]{3,10})$","description":"Stock ticker symbol (e.g., TSLA, $AAPL, BRK.A)","examples":["TSLA","BRK.A"],"title":"Ticker"},"description":"Stock ticker symbol (e.g., TSLA, $AAPL, BRK.A)"},{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of raw tweet rows to return","examples":[50],"default":50,"title":"Limit"},"description":"Maximum number of raw tweet rows to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of raw mention rows to skip for offset-based pagination.","examples":[0],"default":0,"title":"Offset"},"description":"Number of raw mention rows to skip for offset-based pagination."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XRawMentionsResponse"},"example":{"ticker":"NVDA","period_days":7,"count":1,"results":[{"tweet_id":"1901234567890","author":"marketwatcher","text_snippet":"$NVDA still has room after the pullback...","created_utc":"2026-03-20T14:11:02Z","likes":942,"retweets":88,"views":52110,"is_reply":false,"sentiment_score":0.44,"sentiment_label":"positive"}]}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=60"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Getxstockrawmentions"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/x/stocks/v1/stock/TSLA/mentions?from=2026-05-01&to=2026-05-07&limit=5\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/x/stocks/v1/stock/TSLA/mentions?from=2026-05-01&to=2026-05-07&limit=5\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/x/stocks/v1/stock/TSLA/mentions?from=2026-05-01&to=2026-05-07&limit=5\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/polymarket/stocks/v1/trending":{"get":{"tags":["Polymarket Stocks"],"summary":"Trending stocks","description":"Returns the stocks with the strongest Polymarket prediction-market activity in the selected period, ranked by `buzz_score`.\n\n**Includes:**\n- `buzz_score`: normalized 0-100 activity score used for ranking; bullish and bearish market activity can both rank highly\n- `trend`: flow momentum over the current 3 UTC days vs previous 3 UTC days using trades, volume, market breadth and liquidity; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: outcome-aware market sentiment signals\n- `trade_count`, `market_count`, `unique_traders`, `total_liquidity`: activity, breadth, observed participation and liquidity signals\n- `trend_history`: independent UTC-day buzz scores, oldest to newest; minimum 7 values. For a closed single-day window with an available final Daily score, the final value equals `buzz_score`; live and multi-day values can differ. Missing days are `0.0`","operationId":"getPolymarketTrendingStocks","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum stocks to return","examples":[20],"default":20,"title":"Limit"},"description":"Maximum stocks to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of items to skip","examples":[0],"default":0,"title":"Offset"},"description":"Number of items to skip"},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["stock","etf","all"],"type":"string"},{"type":"null"}],"description":"Filter by asset type. Omit or use 'all' for all assets.","examples":["stock"],"title":"Type"},"description":"Filter by asset type. Omit or use 'all' for all assets."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PolymarketTrendingStock"},"title":"Response Getpolymarkettrendingstocks"},"example":[{"ticker":"TSLA","company_name":"Tesla, Inc.","buzz_score":71.4,"trend":"rising","trade_count":312,"market_count":27,"current_market_count":12,"unique_traders":119,"sentiment_score":0.34,"bullish_pct":67,"bearish_pct":33,"total_liquidity":94750.0,"trend_history":[48.2,51.0,55.3,61.1,65.8,69.2,71.4]}]}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=30"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Getpolymarkettrendingstocks"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/polymarket/stocks/v1/trending?from=2026-05-01&to=2026-05-07&limit=5\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/polymarket/stocks/v1/trending?from=2026-05-01&to=2026-05-07&limit=5\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/polymarket/stocks/v1/trending?from=2026-05-01&to=2026-05-07&limit=5\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/polymarket/stocks/v1/trending/sectors":{"get":{"tags":["Polymarket Stocks"],"summary":"Trending sectors","description":"Returns the sectors with the strongest aggregated Polymarket prediction-market activity in the selected period, ranked by `buzz_score`.\n\n**Includes:**\n- `buzz_score`: normalized 0-100 activity score used for ranking\n- `trend`: flow momentum over the current 3 UTC days vs previous 3 UTC days using trades, volume, market breadth and liquidity; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)\n- `trade_count`, `market_count`, `unique_traders`, `total_liquidity`: activity, breadth, observed participation and liquidity signals\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: outcome-aware market sentiment signals\n- `top_tickers`: up to 5 tickers driving the sector result","operationId":"getPolymarketTrendingSectors","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum sectors to return","examples":[20],"default":20,"title":"Limit"},"description":"Maximum sectors to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of items to skip","examples":[0],"default":0,"title":"Offset"},"description":"Number of items to skip"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PolymarketTrendingSector"},"title":"Response Getpolymarkettrendingsectors"},"example":[{"buzz_score":72.8,"trend":"rising","trade_count":312,"market_count":147,"current_market_count":71,"unique_tickers":6,"unique_traders":211,"sentiment_score":0.22,"bullish_pct":61,"bearish_pct":39,"total_liquidity":325000.0,"trend_history":[48.2,51.0,55.3,61.1,65.8,69.2,72.8],"top_tickers":["AAPL","MSFT","NVDA","TSLA","AMD"],"sector":"Technology"}]}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=300"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Getpolymarkettrendingsectors"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/polymarket/stocks/v1/trending/sectors?from=2026-05-01&to=2026-05-07&limit=5\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/polymarket/stocks/v1/trending/sectors?from=2026-05-01&to=2026-05-07&limit=5\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/polymarket/stocks/v1/trending/sectors?from=2026-05-01&to=2026-05-07&limit=5\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/polymarket/stocks/v1/trending/countries":{"get":{"tags":["Polymarket Stocks"],"summary":"Trending countries","description":"Returns the countries with the strongest aggregated Polymarket prediction-market activity in the selected period, ranked by `buzz_score`.\n\n**Includes:**\n- `buzz_score`: normalized 0-100 activity score used for ranking\n- `trend`: flow momentum over the current 3 UTC days vs previous 3 UTC days using trades, volume, market breadth and liquidity; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)\n- `trade_count`, `market_count`, `unique_traders`, `total_liquidity`: activity, breadth, observed participation and liquidity signals\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: outcome-aware market sentiment signals\n- `top_tickers`: up to 5 tickers driving the country result","operationId":"getPolymarketTrendingCountries","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum countries to return","examples":[20],"default":20,"title":"Limit"},"description":"Maximum countries to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of items to skip","examples":[0],"default":0,"title":"Offset"},"description":"Number of items to skip"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PolymarketTrendingCountry"},"title":"Response Getpolymarkettrendingcountries"},"example":[{"buzz_score":70.1,"trend":"stable","trade_count":712,"market_count":265,"current_market_count":129,"unique_tickers":10,"unique_traders":402,"sentiment_score":0.18,"bullish_pct":58,"bearish_pct":42,"total_liquidity":472000.0,"trend_history":[52.1,54.0,56.8,59.2,61.0,60.1,70.1],"top_tickers":["AAPL","TSLA","NVDA","AMZN","GOOGL"],"country":"United States"}]}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=300"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Getpolymarkettrendingcountries"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/polymarket/stocks/v1/trending/countries?from=2026-05-01&to=2026-05-07&limit=5\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/polymarket/stocks/v1/trending/countries?from=2026-05-01&to=2026-05-07&limit=5\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/polymarket/stocks/v1/trending/countries?from=2026-05-01&to=2026-05-07&limit=5\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/polymarket/stocks/v1/stock/{ticker}":{"get":{"tags":["Polymarket Stocks"],"summary":"Stock sentiment","description":"Returns Polymarket-based sentiment and activity for one stock ticker.\n\nThe response combines:\n- Period metrics for the date window defined by `from`/`to`.\n- Representative market-level evidence in `top_mentions`.\n- A compact current market read in `pulse`.\n\n**Fields:**\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: outcome-aware sentiment derived from Polymarket market prices and outcomes\n- `buzz_score`: normalized activity score for the selected period; both bullish and bearish activity can increase buzz\n- `trend`: recent flow momentum, comparing the current 3 UTC days with the previous 3 UTC days using trades, volume, market breadth and liquidity; this is not stock price movement\n- `trade_count`, `market_count`, `unique_traders`, `total_liquidity`: period activity, breadth, observed participation and liquidity\n- `daily_trend`: daily activity and sentiment values for the selected window\n- `top_mentions`: representative Polymarket markets behind the ticker-level signals, including market-level `sentiment_score` and `buzz_score`\n- `pulse`: compact current interpretation from the latest stored open-market snapshots\n\n**Notes:**\n- `pulse` describes the current state and does not repeat the aggregate fields. Use `top_mentions` for concrete market examples.\n- `top_mentions` includes only markets observed active/open in the selected period; ranking prioritizes outcome-aware directional evidence, keeps opposing signals visible when present, then uses trade count, market status, volume and liquidity as tie-breakers.\n- Prices, volume and liquidity in `top_mentions` come from the selected in-period snapshot, not necessarily the latest live market state.\n- `active` indicates whether the market is currently open, so older in-period evidence can now be inactive, resolved or expired.\n- `market_status` can be `tradable`, `open`, `resolved`, `expired` or `inactive`.\n- For windows longer than snapshot retention, aggregate metrics still come from daily aggregates, while `top_mentions` is limited to retained market snapshots.\n- Returns `200` with `found: false` when the ticker is supported but this service has no qualifying data in the requested window. Returns `404` only when the ticker is unsupported.","operationId":"getPolymarketStock","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","pattern":"^\\$?(?:[A-Za-z0-9]{1,8}[.-][A-Za-z]|[A-Za-z0-9]{0}[A-Za-z][A-Za-z0-9]{0,9}|[A-Za-z0-9]{1}[A-Za-z][A-Za-z0-9]{0,8}|[A-Za-z0-9]{2}[A-Za-z][A-Za-z0-9]{0,7}|[A-Za-z0-9]{3}[A-Za-z][A-Za-z0-9]{0,6}|[A-Za-z0-9]{4}[A-Za-z][A-Za-z0-9]{0,5}|[A-Za-z0-9]{5}[A-Za-z][A-Za-z0-9]{0,4}|[A-Za-z0-9]{6}[A-Za-z][A-Za-z0-9]{0,3}|[A-Za-z0-9]{7}[A-Za-z][A-Za-z0-9]{0,2}|[A-Za-z0-9]{8}[A-Za-z][A-Za-z0-9]{0,1}|[A-Za-z0-9]{9}[A-Za-z][A-Za-z0-9]{0,0}|[0-9]{3,10})$","description":"Stock ticker symbol (e.g., TSLA, $AAPL, BRK.A)","examples":["AAPL","BRK.A"],"title":"Ticker"},"description":"Stock ticker symbol (e.g., TSLA, $AAPL, BRK.A)"},{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolymarketStockDetailResponse"},"example":{"ticker":"AAPL","company_name":"Apple Inc.","found":true,"buzz_score":68.9,"trend":"stable","period_days":7,"trade_count":312,"market_count":27,"current_market_count":12,"unique_traders":119,"sentiment_score":0.28,"bullish_pct":64,"bearish_pct":36,"total_liquidity":128000.0,"daily_trend":[{"date":"2026-02-13","trade_count":5,"sentiment_score":0.25,"buzz_score":64.1,"bullish_pct":64,"bearish_pct":21}],"top_mentions":[{"condition_id":"0xabc...","question":"Will AAPL close above $220 this week?","market_type":"close_above","trade_count":42,"sentiment_score":0.23,"buzz_score":77.2,"yes_price":0.62,"no_price":0.38,"liquidity":7905.52,"volume_24h":2408.43,"end_date":"2026-02-28","active":true,"market_status":"tradable"}],"pulse":{"mood":"mixed","confidence":60.0,"thin_data":false,"why":["opposing_market_signals","upside_targets_rejected","floor_support"],"warnings":["high_average_spread","low_trade_breadth"],"evidence":{"directional_coverage":1.0,"traded_market_pct":0.231,"zero_trade_market_pct":0.769,"avg_spread":0.099,"snapshot_at":"2026-06-24T06:25:53Z"}}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=30"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Getpolymarketstock"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Unsupported ticker","content":{"application/json":{"example":{"detail":{"error_code":"unsupported_ticker","message":"Unsupported ticker $XYZ. This ticker is not supported by Adanos v1."}},"schema":{"$ref":"#/components/schemas/UnsupportedAssetError"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/polymarket/stocks/v1/stock/AAPL?from=2026-05-01&to=2026-05-07\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/polymarket/stocks/v1/stock/AAPL?from=2026-05-01&to=2026-05-07\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/polymarket/stocks/v1/stock/AAPL?from=2026-05-01&to=2026-05-07\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/polymarket/stocks/v1/market-sentiment":{"get":{"tags":["Polymarket Stocks"],"summary":"Market sentiment","description":"Returns one reading for all stock-related Polymarket activity: overall buzz, sentiment split, activity trend, breadth and the `drivers` behind it, ranked by `buzz_score`.\n\nHere `buzz_score` compares overall Polymarket stock-market activity with its own trailing 90-day baseline:\n- around `50` = normal market activity\n- higher = more active than usual\n- lower = quieter than usual\n\n`trend` is flow momentum over the current 3 UTC days vs previous 3 UTC days using trades, volume, market breadth and liquidity; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).\n\nUse `sentiment_score`, `bullish_pct` and `bearish_pct` for direction.","operationId":"getPolymarketMarketSentiment","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolymarketMarketSentimentResponse"},"example":{"buzz_score":58.4,"trend":"stable","trade_count":512,"market_count":93,"current_market_count":64,"unique_traders":281,"total_liquidity":245000.0,"active_tickers":31,"sentiment_score":0.11,"positive_count":41,"negative_count":29,"neutral_count":23,"bullish_pct":44,"bearish_pct":31,"trend_history":[52.1,54.0,56.8,59.2,61.0,60.1,58.4],"drivers":[{"ticker":"AAPL","trade_count":52,"buzz_score":68.9,"sentiment_score":0.28},{"ticker":"TSLA","trade_count":47,"buzz_score":66.3,"sentiment_score":0.19}]}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=300"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Getpolymarketmarketsentiment"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/polymarket/stocks/v1/market-sentiment?from=2026-05-01&to=2026-05-07\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/polymarket/stocks/v1/market-sentiment?from=2026-05-01&to=2026-05-07\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/polymarket/stocks/v1/market-sentiment?from=2026-05-01&to=2026-05-07\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/polymarket/stocks/v1/compare":{"get":{"tags":["Polymarket Stocks"],"summary":"Compare stocks","description":"Compare up to 10 stock or ETF tickers side by side using Polymarket market activity.\n\nUse it for watchlists: one compact row per ticker.\nResults are sorted by `buzz_score` descending and include `trend`, `trend_history`, `trade_count`, `market_count`, `current_market_count`, `unique_traders`, `sentiment_score`, `bullish_pct`, `bearish_pct` and `total_liquidity`.\n`trend` is flow momentum over the current 3 UTC days vs previous 3 UTC days using trades, volume, market breadth and liquidity; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).\nEach requested ticker gets one row. Tickers without activity in the period, including unsupported ones, return zeroed metrics. Unsupported tickers have no company name; use `/search` to check support.","operationId":"comparePolymarketStocks","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."},{"name":"tickers","in":"query","required":true,"schema":{"type":"string","description":"Comma-separated ticker list (max 10)","examples":["TSLA,NVDA,AMD"],"title":"Tickers"},"description":"Comma-separated ticker list (max 10)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolymarketCompareResponse"},"example":{"period_days":7,"stocks":[{"ticker":"AAPL","company_name":"Apple Inc.","buzz_score":68.9,"trend":"stable","trade_count":312,"market_count":27,"current_market_count":12,"unique_traders":119,"sentiment_score":0.28,"bullish_pct":64,"bearish_pct":36,"total_liquidity":128000.0,"trend_history":[48.2,51.0,55.3,61.1,65.8,69.2,68.9]}]}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=30"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Comparepolymarketstocks"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"400":{"description":"Invalid compare item list","content":{"application/json":{"example":{"detail":{"error":"too_many_tickers","message":"Maximum 10 tickers allowed.","max_items":10,"item_name":"ticker"}},"examples":{"too_many_tickers":{"summary":"Too many tickers","value":{"detail":{"error":"too_many_tickers","message":"Maximum 10 tickers allowed.","max_items":10,"item_name":"ticker"}}},"no_valid_tickers":{"summary":"No valid tickers","value":{"detail":{"error":"no_valid_tickers","message":"At least one valid ticker is required.","max_items":10,"item_name":"ticker"}}}},"schema":{"$ref":"#/components/schemas/CompareLimitError"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/polymarket/stocks/v1/compare?from=2026-05-01&to=2026-05-07&tickers=TSLA,AAPL,NVDA\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/polymarket/stocks/v1/compare?from=2026-05-01&to=2026-05-07&tickers=TSLA,AAPL,NVDA\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/polymarket/stocks/v1/compare?from=2026-05-01&to=2026-05-07&tickers=TSLA,AAPL,NVDA\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/polymarket/stocks/v1/search":{"get":{"tags":["Polymarket Stocks"],"summary":"Search stocks","description":"Search supported stocks and ETFs, then enrich the matches with Polymarket activity. Results prioritize exact ticker matches first, then prefixes, then name/alias matches and include a compact `summary` block for the last 7 UTC calendar days.","operationId":"searchPolymarketStocks","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":50,"description":"Search query (minimum 2 non-$ characters after trimming)","examples":["tesla"],"title":"Q"},"description":"Search query (minimum 2 non-$ characters after trimming)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"Maximum number of results to return","examples":[20],"default":20,"title":"Limit"},"description":"Maximum number of results to return"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolymarketSearchResponse"},"example":{"query":"tesla","count":1,"period_days":7,"results":[{"ticker":"TSLA","name":"Tesla Inc.","type":"Stock","exchange":"NASDAQ","sector":"Consumer Discretionary","country":"United States","aliases":["Tesla","Elon"],"summary":{"trade_count":14,"buzz_score":71.4,"trend":"rising","sentiment_score":0.34,"bearish_pct":33,"bullish_pct":67,"current_market_count":12,"market_count":27,"total_liquidity":94750.0,"unique_traders":119}}]}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=15"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Invalid search query parameters","content":{"application/json":{"examples":{"fixed_window":{"summary":"Search endpoints use a fixed summary window","value":{"detail":{"error":"Invalid search parameters","message":"Search endpoints use a fixed last-7-UTC-calendar-day summary window.","unsupported_parameters":["days"]}}},"normalized_query":{"summary":"Search query is too short after normalization","value":{"detail":"Search query must contain at least 2 non-$ characters after trimming"}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"string_too_short","loc":["query","q"],"msg":"String should have at least 2 characters","input":"t","ctx":{"min_length":2}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidSearchParametersError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Searchpolymarketstocks"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/polymarket/stocks/v1/search?q=tesla&limit=5\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/polymarket/stocks/v1/search?q=tesla&limit=5\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/polymarket/stocks/v1/search?q=tesla&limit=5\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/polymarket/stocks/v1/stats":{"get":{"tags":["Polymarket Stocks"],"summary":"Dataset statistics","description":"Returns high-level database coverage metrics for the Polymarket stock dataset.\n\nUse this endpoint to understand how much market activity is indexed:\n- total aggregated trade activity\n- total distinct markets captured\n- unique stock tickers with indexed Polymarket market rows\n- currently open markets and tickers\n- today's UTC trade activity, traded markets and traded tickers\n- supported ticker count from the reference universe","operationId":"getPolymarketStats","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolymarketStatsResponse"},"example":{"total_trades":15420,"total_markets":713,"unique_tickers":119,"open_markets_current":284,"open_tickers_current":71,"traded_markets_today":39,"traded_tickers_today":17,"trades_today":84,"supported_tickers":35000}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=300"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"},"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Database temporarily unavailable"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Request deadline exceeded"}}}}},"security":[{"ApiKeyAuth":[]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/polymarket/stocks/v1/stats\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/polymarket/stocks/v1/stats\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/polymarket/stocks/v1/stats\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/polymarket/stocks/v1/stock/{ticker}/mentions":{"get":{"tags":["Polymarket Stocks"],"summary":"Raw mentions","description":"Returns raw Polymarket market snapshot rows for a specific ticker within the live raw-data retention window.\n**Professional account required.** Free and Hobby accounts cannot use this endpoint.\n\n**Use this endpoint when you need:**\n- original market questions, prices, liquidity, volume, trade counters and timestamps\n- outcome-aware market price sentiment for individual snapshot rows\n- repeated snapshots for the same market over time\n\n**Notes:**\n- Use `from` and `to` for explicit UTC date windows\n- Results are ordered newest first and support deterministic `offset` + `limit` pagination\n- empty result sets return `200` with `results=[]`\n- The same `condition_id` can appear multiple times across different `fetched_at` snapshots\n- `active` indicates whether the market is currently open, using the latest stored state for that `condition_id`; `market_status` compactly distinguishes `tradable`, `open`, `resolved`, `expired` and `inactive`\n- `buy_trades` and `sell_trades` are activity counters, not bullish/bearish sentiment","operationId":"getPolymarketStockRawMentions","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","pattern":"^\\$?(?:[A-Za-z0-9]{1,8}[.-][A-Za-z]|[A-Za-z0-9]{0}[A-Za-z][A-Za-z0-9]{0,9}|[A-Za-z0-9]{1}[A-Za-z][A-Za-z0-9]{0,8}|[A-Za-z0-9]{2}[A-Za-z][A-Za-z0-9]{0,7}|[A-Za-z0-9]{3}[A-Za-z][A-Za-z0-9]{0,6}|[A-Za-z0-9]{4}[A-Za-z][A-Za-z0-9]{0,5}|[A-Za-z0-9]{5}[A-Za-z][A-Za-z0-9]{0,4}|[A-Za-z0-9]{6}[A-Za-z][A-Za-z0-9]{0,3}|[A-Za-z0-9]{7}[A-Za-z][A-Za-z0-9]{0,2}|[A-Za-z0-9]{8}[A-Za-z][A-Za-z0-9]{0,1}|[A-Za-z0-9]{9}[A-Za-z][A-Za-z0-9]{0,0}|[0-9]{3,10})$","description":"Stock ticker symbol (e.g., TSLA, $AAPL, BRK.A)","examples":["TSLA","BRK.A"],"title":"Ticker"},"description":"Stock ticker symbol (e.g., TSLA, $AAPL, BRK.A)"},{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of raw Polymarket snapshot rows to return","examples":[50],"default":50,"title":"Limit"},"description":"Maximum number of raw Polymarket snapshot rows to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of raw mention rows to skip for offset-based pagination.","examples":[0],"default":0,"title":"Offset"},"description":"Number of raw mention rows to skip for offset-based pagination."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolymarketRawMentionsResponse"},"example":{"ticker":"NVDA","period_days":7,"count":1,"results":[{"condition_id":"0xabc...","event_id":"12345","market_slug":"nvda-up-or-down-on-april-20-2026","question":"NVDA up or down on April 20?","market_type":"up_down","strike_price":250.0,"yes_price":0.63,"no_price":0.37,"reference_price":247.82,"reference_price_timestamp":"2026-04-20T14:30:00Z","liquidity":7905.52,"volume_24h":2408.43,"trade_count":42,"buy_trades":23,"sell_trades":19,"unique_traders":31,"sentiment_score":0.26,"sentiment_label":"positive","end_date":"2026-04-20T23:59:00Z","active":true,"market_status":"tradable","fetched_at":"2026-04-20T15:00:00Z"}]}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=60"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Getpolymarketstockrawmentions"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/polymarket/stocks/v1/stock/TSLA/mentions?from=2026-05-01&to=2026-05-07&limit=5\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/polymarket/stocks/v1/stock/TSLA/mentions?from=2026-05-01&to=2026-05-07&limit=5\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/polymarket/stocks/v1/stock/TSLA/mentions?from=2026-05-01&to=2026-05-07&limit=5\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/news/stocks/v1/trending":{"get":{"tags":["News Stocks"],"summary":"Trending stocks","description":"Returns the stocks with the strongest news coverage activity in the selected period, ranked by `buzz_score`.\n\n**Includes:**\n- `buzz_score`: normalized 0-100 activity score used for ranking\n- `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions/articles and source breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals\n- `mentions`, `source_count`: coverage volume and source breadth signals\n- `trend_history`: independent UTC-day buzz scores, oldest to newest; minimum 7 values; the live final value describes today so far and can differ from the selected-period `buzz_score`; missing days are `0.0`\n\nUse `source` only when you want the ranking filtered to one publisher or source family.","operationId":"getNewsTrendingStocks","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of results","default":20,"title":"Limit"},"description":"Maximum number of results"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of items to skip for pagination","default":0,"title":"Offset"},"description":"Number of items to skip for pagination"},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["stock","etf","all"],"type":"string"},{"type":"null"}],"description":"Filter by asset type. Omit or use 'all' for all assets.","title":"Type"},"description":"Filter by asset type. Omit or use 'all' for all assets."},{"name":"source","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional source filter (strict canonical source id or known alias)","title":"Source"},"description":"Optional source filter (strict canonical source id or known alias)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/NewsTrendingStock"},"title":"Response Getnewstrendingstocks"},"example":[{"ticker":"TSLA","company_name":"Tesla, Inc.","buzz_score":87.5,"trend":"rising","mentions":342,"source_count":8,"sentiment_score":0.23,"bullish_pct":45,"bearish_pct":18,"trend_history":[45.2,52.1,48.7,67.3,72.1,78.4,87.5]}]}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=30"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Getnewstrendingstocks"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No trending stocks found","content":{"application/json":{"example":{"detail":"No trending stocks found."}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/news/stocks/v1/trending?from=2026-05-01&to=2026-05-07&limit=5\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/news/stocks/v1/trending?from=2026-05-01&to=2026-05-07&limit=5\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/news/stocks/v1/trending?from=2026-05-01&to=2026-05-07&limit=5\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/news/stocks/v1/trending/sectors":{"get":{"tags":["News Stocks"],"summary":"Trending sectors","description":"Returns the sectors with the strongest aggregated news coverage activity in the selected period, ranked by `buzz_score`.\n\n**Includes:**\n- `buzz_score`: normalized 0-100 activity score used for ranking\n- `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions/articles and source breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)\n- `mentions`, `unique_tickers`, `source_count`: coverage volume and breadth signals\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals\n- `top_tickers`: up to 5 tickers driving the sector result\n\nUse `source` only when you want the ranking filtered to one publisher or source family.","operationId":"getNewsTrendingSectors","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of results","default":20,"title":"Limit"},"description":"Maximum number of results"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of items to skip for pagination","default":0,"title":"Offset"},"description":"Number of items to skip for pagination"},{"name":"source","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional source filter (strict canonical source id or known alias)","title":"Source"},"description":"Optional source filter (strict canonical source id or known alias)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/NewsTrendingSector"},"title":"Response Getnewstrendingsectors"},"example":[{"buzz_score":78.4,"trend":"rising","mentions":4523,"unique_tickers":34,"source_count":15,"sentiment_score":0.28,"bullish_pct":54,"bearish_pct":22,"trend_history":[45.2,48.1,52.3,55.0,58.2,61.5,78.4],"top_tickers":["NVDA","AAPL","MSFT","AMD","GOOGL"],"sector":"Technology"}]}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=300"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Getnewstrendingsectors"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No trending sectors found","content":{"application/json":{"example":{"detail":"No trending sectors found."}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/news/stocks/v1/trending/sectors?from=2026-05-01&to=2026-05-07&limit=5\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/news/stocks/v1/trending/sectors?from=2026-05-01&to=2026-05-07&limit=5\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/news/stocks/v1/trending/sectors?from=2026-05-01&to=2026-05-07&limit=5\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/news/stocks/v1/trending/countries":{"get":{"tags":["News Stocks"],"summary":"Trending countries","description":"Returns the countries with the strongest aggregated news coverage activity in the selected period, ranked by `buzz_score`.\n\n**Includes:**\n- `buzz_score`: normalized 0-100 activity score used for ranking\n- `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions/articles and source breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)\n- `mentions`, `unique_tickers`, `source_count`: coverage volume and breadth signals\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals\n- `top_tickers`: up to 5 tickers driving the country result\n\nUse `source` only when you want the ranking filtered to one publisher or source family.","operationId":"getNewsTrendingCountries","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of results","default":20,"title":"Limit"},"description":"Maximum number of results"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of items to skip for pagination","default":0,"title":"Offset"},"description":"Number of items to skip for pagination"},{"name":"source","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional source filter (strict canonical source id or known alias)","title":"Source"},"description":"Optional source filter (strict canonical source id or known alias)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/NewsTrendingCountry"},"title":"Response Getnewstrendingcountries"},"example":[{"buzz_score":82.3,"trend":"stable","mentions":8934,"unique_tickers":156,"source_count":18,"sentiment_score":0.21,"bullish_pct":48,"bearish_pct":26,"trend_history":[52.1,54.0,56.8,59.2,61.0,60.1,82.3],"top_tickers":["NVDA","TSLA","AAPL","AMD","PLTR"],"country":"United States"}]}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=300"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Getnewstrendingcountries"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No trending countries found","content":{"application/json":{"example":{"detail":"No trending countries found."}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/news/stocks/v1/trending/countries?from=2026-05-01&to=2026-05-07&limit=5\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/news/stocks/v1/trending/countries?from=2026-05-01&to=2026-05-07&limit=5\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/news/stocks/v1/trending/countries?from=2026-05-01&to=2026-05-07&limit=5\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/news/stocks/v1/stock/{ticker}":{"get":{"tags":["News Stocks"],"summary":"Stock sentiment","description":"Returns the news report for one stock ticker.\n\n**Includes:**\n- `buzz_score`: normalized news activity score for the selected period\n- `trend`: activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions/articles and source breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)\n- `sentiment_score`, `bullish_pct`, `bearish_pct`: directional sentiment signals\n- `mentions`, `source_count`: coverage volume and source breadth signals\n- `daily_trend`: daily news activity and sentiment values\n- `top_mentions`: representative recent articles from the selected period, with source attribution\n- `top_sources`: top source contributors by mention count\n\nReturns `200` with `found: false` when the ticker is supported but this service\nhas no qualifying data in the requested window. Returns `404` only when the\nticker is unsupported.","operationId":"getNewsStockSentiment","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","pattern":"^(?=[A-Za-z0-9.]{1,32}$)[A-Za-z0-9]+(?:\\.(?:[Aa][Ee]|[Aa][Ss]|[Aa][Tt]|[Aa][Xx]|[Bb][Aa]|[Bb][Dd]|[Bb][Kk]|[Bb][Oo]|[Bb][Rr]|[Cc][Aa]|[Cc][Ll]|[Cc][Nn]|[Cc][Oo]|[Dd][Ee]|[Dd][Uu]|[Ff]|[Hh][Aa]|[Hh][Ee]|[Hh][Kk]|[Hh][Mm]|[Ii][Cc]|[Ii][Rr]|[Ii][Ss]|[Jj][Kk]|[Jj][Oo]|[Kk][Ll]|[Kk][Qq]|[Kk][Ss]|[Kk][Ww]|[Ll]|[Ll][Ss]|[Mm][Cc]|[Mm][Ii]|[Mm][Uu]|[Mm][Xx]|[Nn][Ee]|[Nn][Ss]|[Nn][Zz]|[Oo][Ll]|[Pp][Aa]|[Pp][Rr]|[Pp][Ss]|[Qq][Aa]|[Rr][Oo]|[Ss][Aa]|[Ss][Aa][Uu]|[Ss][Gg]|[Ss][Ii]|[Ss][Nn]|[Ss][Ss]|[Ss][Tt]|[Ss][Ww]|[Ss][Zz]|[Tt]|[Tt][Aa]|[Tt][Oo]|[Tt][Ww]|[Tt][Ww][Oo]|[Vv]|[Vv][Ii]|[Vv][Nn]|[Ww][Aa]))?$(?![\\s\\S])","description":"News company key: 1-32 ASCII letters/digits with an optional documented venue suffix, case-insensitive. Examples: BRK, EADSY, ABX.DE. Share classes (BRK.A, BRK.B, BRK-B), hyphens, ampersands, cashtags and unknown suffixes return 422. A documented suffix resolves only if assigned to that issuer; other well-formed keys return 404. One issuer is one time series; ETFs stay separate issuers. Venue suffixes: .AE, .AS, .AT, .AX, .BA, .BD, .BK, .BO, .BR, .CA, .CL, .CN, .CO, .DE, .DU, .F, .HA, .HE, .HK, .HM, .IC, .IR, .IS, .JK, .JO, .KL, .KQ, .KS, .KW, .L, .LS, .MC, .MI, .MU, .MX, .NE, .NS, .NZ, .OL, .PA, .PR, .PS, .QA, .RO, .SA, .SAU, .SG, .SI, .SN, .SS, .ST, .SW, .SZ, .T, .TA, .TO, .TW, .TWO, .V, .VI, .VN, .WA.","title":"Ticker"},"description":"News company key: 1-32 ASCII letters/digits with an optional documented venue suffix, case-insensitive. Examples: BRK, EADSY, ABX.DE. Share classes (BRK.A, BRK.B, BRK-B), hyphens, ampersands, cashtags and unknown suffixes return 422. A documented suffix resolves only if assigned to that issuer; other well-formed keys return 404. One issuer is one time series; ETFs stay separate issuers. Venue suffixes: .AE, .AS, .AT, .AX, .BA, .BD, .BK, .BO, .BR, .CA, .CL, .CN, .CO, .DE, .DU, .F, .HA, .HE, .HK, .HM, .IC, .IR, .IS, .JK, .JO, .KL, .KQ, .KS, .KW, .L, .LS, .MC, .MI, .MU, .MX, .NE, .NS, .NZ, .OL, .PA, .PR, .PS, .QA, .RO, .SA, .SAU, .SG, .SI, .SN, .SS, .ST, .SW, .SZ, .T, .TA, .TO, .TW, .TWO, .V, .VI, .VN, .WA."},{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewsStockSentiment"},"example":{"ticker":"TSLA","company_name":"Tesla, Inc.","found":true,"buzz_score":87.5,"mentions":342,"sentiment_score":0.23,"source_count":8,"trend":"rising","bullish_pct":45,"bearish_pct":18,"period_days":7,"top_sources":[{"source":"reuters","mentions":89,"count":89},{"source":"benzinga","mentions":67,"count":67}],"daily_trend":[{"date":"2026-03-05","mentions":52,"sentiment_score":0.31,"buzz_score":42.8,"bullish_pct":58,"bearish_pct":19},{"date":"2026-03-04","mentions":48,"sentiment_score":0.18,"buzz_score":38.5,"bullish_pct":46,"bearish_pct":21}],"top_mentions":[{"text_snippet":"TSLA looking strong after production update...","sentiment_score":0.85,"sentiment_label":"positive","source":"reuters","created_utc":"2026-03-05T10:30:00+00:00"}]}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=30"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Getnewsstocksentiment"}}}},"503":{"description":"News identity lookup or database service unavailable; no Legacy fallback is used","content":{"application/json":{"example":{"detail":"News identity lookup unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Unsupported ticker","content":{"application/json":{"example":{"detail":{"error_code":"unsupported_ticker","message":"Unsupported ticker $XYZ. This ticker is not supported by Adanos v1."}},"schema":{"$ref":"#/components/schemas/UnsupportedAssetError"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/news/stocks/v1/stock/TSLA?from=2026-05-01&to=2026-05-07\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/news/stocks/v1/stock/TSLA?from=2026-05-01&to=2026-05-07\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/news/stocks/v1/stock/TSLA?from=2026-05-01&to=2026-05-07\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/news/stocks/v1/market-sentiment":{"get":{"tags":["News Stocks"],"summary":"Market sentiment","description":"Returns one reading for all stock news coverage: overall buzz, sentiment split, activity trend, breadth and the `drivers` behind it, ranked by `buzz_score`.\n\nHere `buzz_score` compares overall stock news flow with its own trailing 90-day baseline:\n- around `50` = normal news activity\n- higher = broader coverage than usual\n- lower = quieter than usual\n\n`trend` is activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions/articles and source breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).\n\nUse `sentiment_score`, `bullish_pct` and `bearish_pct` for direction.","operationId":"getNewsMarketSentiment","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewsMarketSentimentResponse"},"example":{"buzz_score":53.8,"trend":"stable","mentions":1298,"unique_articles":911,"source_count":44,"active_tickers":233,"sentiment_score":0.064,"positive_count":512,"negative_count":308,"neutral_count":478,"bullish_pct":39,"bearish_pct":24,"trend_history":[49.1,50.4,48.7,52.2,55.1,54.3,53.8],"drivers":[{"ticker":"AAPL","mentions":87,"buzz_score":69.7,"sentiment_score":0.22},{"ticker":"NVDA","mentions":76,"buzz_score":67.3,"sentiment_score":0.31}]}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=300"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Getnewsmarketsentiment"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/news/stocks/v1/market-sentiment?from=2026-05-01&to=2026-05-07\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/news/stocks/v1/market-sentiment?from=2026-05-01&to=2026-05-07\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/news/stocks/v1/market-sentiment?from=2026-05-01&to=2026-05-07\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/news/stocks/v1/stock/{ticker}/explain":{"get":{"tags":["News Stocks"],"summary":"AI explanation","description":"Returns an AI-generated explanation for why a stock is trending in the news dataset, anchored to article evidence.\n\n**Includes:**\n- `explanation`: 1-2 sentence summary of why the stock is trending\n- `cached`: whether this was served from cache\n- `generated_at`: when the explanation was generated\n- `model`: the language model that wrote the explanation","operationId":"getNewsStockExplanation","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","pattern":"^(?=[A-Za-z0-9.]{1,32}$)[A-Za-z0-9]+(?:\\.(?:[Aa][Ee]|[Aa][Ss]|[Aa][Tt]|[Aa][Xx]|[Bb][Aa]|[Bb][Dd]|[Bb][Kk]|[Bb][Oo]|[Bb][Rr]|[Cc][Aa]|[Cc][Ll]|[Cc][Nn]|[Cc][Oo]|[Dd][Ee]|[Dd][Uu]|[Ff]|[Hh][Aa]|[Hh][Ee]|[Hh][Kk]|[Hh][Mm]|[Ii][Cc]|[Ii][Rr]|[Ii][Ss]|[Jj][Kk]|[Jj][Oo]|[Kk][Ll]|[Kk][Qq]|[Kk][Ss]|[Kk][Ww]|[Ll]|[Ll][Ss]|[Mm][Cc]|[Mm][Ii]|[Mm][Uu]|[Mm][Xx]|[Nn][Ee]|[Nn][Ss]|[Nn][Zz]|[Oo][Ll]|[Pp][Aa]|[Pp][Rr]|[Pp][Ss]|[Qq][Aa]|[Rr][Oo]|[Ss][Aa]|[Ss][Aa][Uu]|[Ss][Gg]|[Ss][Ii]|[Ss][Nn]|[Ss][Ss]|[Ss][Tt]|[Ss][Ww]|[Ss][Zz]|[Tt]|[Tt][Aa]|[Tt][Oo]|[Tt][Ww]|[Tt][Ww][Oo]|[Vv]|[Vv][Ii]|[Vv][Nn]|[Ww][Aa]))?$(?![\\s\\S])","description":"News company key: 1-32 ASCII letters/digits with an optional documented venue suffix, case-insensitive. Examples: BRK, EADSY, ABX.DE. Share classes (BRK.A, BRK.B, BRK-B), hyphens, ampersands, cashtags and unknown suffixes return 422. A documented suffix resolves only if assigned to that issuer; other well-formed keys return 404. One issuer is one time series; ETFs stay separate issuers. Venue suffixes: .AE, .AS, .AT, .AX, .BA, .BD, .BK, .BO, .BR, .CA, .CL, .CN, .CO, .DE, .DU, .F, .HA, .HE, .HK, .HM, .IC, .IR, .IS, .JK, .JO, .KL, .KQ, .KS, .KW, .L, .LS, .MC, .MI, .MU, .MX, .NE, .NS, .NZ, .OL, .PA, .PR, .PS, .QA, .RO, .SA, .SAU, .SG, .SI, .SN, .SS, .ST, .SW, .SZ, .T, .TA, .TO, .TW, .TWO, .V, .VI, .VN, .WA.","title":"Ticker"},"description":"News company key: 1-32 ASCII letters/digits with an optional documented venue suffix, case-insensitive. Examples: BRK, EADSY, ABX.DE. Share classes (BRK.A, BRK.B, BRK-B), hyphens, ampersands, cashtags and unknown suffixes return 422. A documented suffix resolves only if assigned to that issuer; other well-formed keys return 404. One issuer is one time series; ETFs stay separate issuers. Venue suffixes: .AE, .AS, .AT, .AX, .BA, .BD, .BK, .BO, .BR, .CA, .CL, .CN, .CO, .DE, .DU, .F, .HA, .HE, .HK, .HM, .IC, .IR, .IS, .JK, .JO, .KL, .KQ, .KS, .KW, .L, .LS, .MC, .MI, .MU, .MX, .NE, .NS, .NZ, .OL, .PA, .PR, .PS, .QA, .RO, .SA, .SAU, .SG, .SI, .SN, .SS, .ST, .SW, .SZ, .T, .TA, .TO, .TW, .TWO, .V, .VI, .VN, .WA."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockExplanationResponse"},"example":{"ticker":"GME","company_name":"Gamestop Corporation - Class A","explanation":"GME is trending due to viral GameStop social media activity and large position posts on r/Superstonk.","cached":true,"generated_at":"2026-01-13T14:30:00+00:00","model":"google/gemma-4-31B-it-turbo"}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=60"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Getnewsstockexplanation"}}}},"503":{"description":"Explanation or database service unavailable","content":{"application/json":{"example":{"detail":"Explanation service temporarily unavailable. Try again later."}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found or no data available for the requested asset/window","content":{"application/json":{"example":{"detail":"No mentions found for $XYZ in the last 7 days."},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/news/stocks/v1/stock/TSLA/explain\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/news/stocks/v1/stock/TSLA/explain\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/news/stocks/v1/stock/TSLA/explain\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/news/stocks/v1/compare":{"get":{"tags":["News Stocks"],"summary":"Compare stocks","description":"Compare up to 10 companies side by side using news coverage.\n\nUse it for watchlists: one compact row per ticker.\nResults are sorted by `buzz_score` descending and include `trend`, `trend_history`, `source_count`, `sentiment_score`, `bullish_pct` and `bearish_pct`.\n`trend` is activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions/articles and source breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).\nEach requested ticker gets one row. Tickers without activity in the period, including unsupported ones, return zeroed metrics. Unsupported tickers have no company name; use `/search` to check support.","operationId":"compareNewsStocks","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."},{"name":"tickers","in":"query","required":true,"schema":{"type":"string","maxLength":512,"description":"Comma-separated News tickers. News company key: 1-32 ASCII letters/digits with an optional documented venue suffix, case-insensitive. Examples: BRK, EADSY, ABX.DE. Share classes (BRK.A, BRK.B, BRK-B), hyphens, ampersands, cashtags and unknown suffixes return 422. A documented suffix resolves only if assigned to that issuer; other well-formed keys return 404. One issuer is one time series; ETFs stay separate issuers. Venue suffixes: .AE, .AS, .AT, .AX, .BA, .BD, .BK, .BO, .BR, .CA, .CL, .CN, .CO, .DE, .DU, .F, .HA, .HE, .HK, .HM, .IC, .IR, .IS, .JK, .JO, .KL, .KQ, .KS, .KW, .L, .LS, .MC, .MI, .MU, .MX, .NE, .NS, .NZ, .OL, .PA, .PR, .PS, .QA, .RO, .SA, .SAU, .SG, .SI, .SN, .SS, .ST, .SW, .SZ, .T, .TA, .TO, .TW, .TWO, .V, .VI, .VN, .WA. Unknown keys and known companies without activity return zero-activity entries; Compare does not distinguish these states. Ambiguous identities return 404.","title":"Tickers"},"description":"Comma-separated News tickers. News company key: 1-32 ASCII letters/digits with an optional documented venue suffix, case-insensitive. Examples: BRK, EADSY, ABX.DE. Share classes (BRK.A, BRK.B, BRK-B), hyphens, ampersands, cashtags and unknown suffixes return 422. A documented suffix resolves only if assigned to that issuer; other well-formed keys return 404. One issuer is one time series; ETFs stay separate issuers. Venue suffixes: .AE, .AS, .AT, .AX, .BA, .BD, .BK, .BO, .BR, .CA, .CL, .CN, .CO, .DE, .DU, .F, .HA, .HE, .HK, .HM, .IC, .IR, .IS, .JK, .JO, .KL, .KQ, .KS, .KW, .L, .LS, .MC, .MI, .MU, .MX, .NE, .NS, .NZ, .OL, .PA, .PR, .PS, .QA, .RO, .SA, .SAU, .SG, .SI, .SN, .SS, .ST, .SW, .SZ, .T, .TA, .TO, .TW, .TWO, .V, .VI, .VN, .WA. Unknown keys and known companies without activity return zero-activity entries; Compare does not distinguish these states. Ambiguous identities return 404."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewsCompareResponse"},"example":{"period_days":7,"stocks":[{"ticker":"TSLA","company_name":"Tesla, Inc.","buzz_score":87.5,"trend":"rising","mentions":342,"source_count":8,"sentiment_score":0.23,"bullish_pct":45,"bearish_pct":18,"trend_history":[45.2,52.1,48.7,67.3,72.1,78.4,87.5]},{"ticker":"NVDA","company_name":"NVIDIA Corporation","buzz_score":72.3,"trend":"stable","mentions":189,"source_count":6,"sentiment_score":0.45,"bullish_pct":51,"bearish_pct":16,"trend_history":[36.5,41.2,46.8,53.4,60.3,66.1,72.3]}]}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=30"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Comparenewsstocks"}}}},"503":{"description":"News identity lookup or database service unavailable; no Legacy fallback is used","content":{"application/json":{"example":{"detail":"News identity lookup unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"400":{"description":"Invalid compare item list","content":{"application/json":{"example":{"detail":{"error":"too_many_tickers","message":"Maximum 10 tickers allowed.","max_items":10,"item_name":"ticker"}},"examples":{"too_many_tickers":{"summary":"Too many tickers","value":{"detail":{"error":"too_many_tickers","message":"Maximum 10 tickers allowed.","max_items":10,"item_name":"ticker"}}},"no_valid_tickers":{"summary":"No valid tickers","value":{"detail":{"error":"no_valid_tickers","message":"At least one valid ticker is required.","max_items":10,"item_name":"ticker"}}}},"schema":{"$ref":"#/components/schemas/CompareLimitError"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/news/stocks/v1/compare?from=2026-05-01&to=2026-05-07&tickers=TSLA,AAPL,NVDA\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/news/stocks/v1/compare?from=2026-05-01&to=2026-05-07&tickers=TSLA,AAPL,NVDA\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/news/stocks/v1/compare?from=2026-05-01&to=2026-05-07&tickers=TSLA,AAPL,NVDA\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/news/stocks/v1/search":{"get":{"tags":["News Stocks"],"summary":"Search stocks","description":"Search stocks by ticker, company name or alias in the News universe. Results prioritize exact ticker matches first, then prefixes, then name/alias matches and include a compact `summary` block for the last 7 UTC calendar days.","operationId":"searchNewsStocks","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":100,"description":"Search query (minimum 2 non-$ characters after trimming)","title":"Q"},"description":"Search query (minimum 2 non-$ characters after trimming)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"Maximum number of results to return","examples":[20],"default":20,"title":"Limit"},"description":"Maximum number of results to return"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewsSearchResponse"},"example":{"query":"tesla","count":1,"period_days":7,"results":[{"ticker":"TSLA","name":"Tesla Inc.","type":"Stock","exchange":"NASDAQ","sector":"Consumer Discretionary","country":"United States","aliases":["TSLA","NASDAQ:TSLA","Tesla"],"summary":{"mentions":342,"buzz_score":87.5,"trend":"rising","sentiment_score":0.23,"bearish_pct":18,"bullish_pct":45,"source_count":8}}]}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=15"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"example":{"detail":"Database temporarily unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Invalid search query parameters","content":{"application/json":{"examples":{"fixed_window":{"summary":"Search endpoints use a fixed summary window","value":{"detail":{"error":"Invalid search parameters","message":"Search endpoints use a fixed last-7-UTC-calendar-day summary window.","unsupported_parameters":["days"]}}},"normalized_query":{"summary":"Search query is too short after normalization","value":{"detail":"Search query must contain at least 2 non-$ characters after trimming"}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"string_too_short","loc":["query","q"],"msg":"String should have at least 2 characters","input":"t","ctx":{"min_length":2}}]}},"source_filter":{"summary":"Source filter is not supported on search","value":{"detail":[{"type":"extra_forbidden","loc":["query","source"],"msg":"Extra inputs are not permitted","input":"wsj"}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidSearchParametersError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Searchnewsstocks"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/news/stocks/v1/search?q=tesla&limit=5\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/news/stocks/v1/search?q=tesla&limit=5\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/news/stocks/v1/search?q=tesla&limit=5\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/news/stocks/v1/stats":{"get":{"tags":["News Stocks"],"summary":"Dataset statistics","description":"Returns high-level coverage statistics for the news stocks dataset.\n\nIncludes:\n- total mention rows stored\n- distinct tickers with news data\n- today's UTC mention and distinct ticker counts\n- total supported tickers in the reference universe","operationId":"getNewsStats","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewsStatsResponse"},"example":{"total_mentions":12833,"unique_tickers":65,"mentions_today":342,"unique_tickers_today":21,"supported_tickers":35000}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=300"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"},"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}}}}},"503":{"description":"Database temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Database temporarily unavailable"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Request deadline exceeded"}}}},"422":{"description":"Unsupported source filter query parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"},"example":{"detail":[{"loc":["query","source"],"msg":"Extra inputs are not permitted","type":"extra_forbidden","input":"wsj"}]}}}}},"security":[{"ApiKeyAuth":[]}],"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/news/stocks/v1/stats\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/news/stocks/v1/stats\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/news/stocks/v1/stats\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/news/stocks/v1/stock/{ticker}/mentions":{"get":{"tags":["News Stocks"],"summary":"Raw mentions","description":"Returns raw news mention rows for a specific stock ticker within the live raw-data retention window.\n**Professional account required.** Free and Hobby accounts cannot use this endpoint.\n\n**Use this endpoint when you need:**\n- article-level snippets\n- original timestamps\n- source attribution for raw rows\n\n**Notes:**\n- Use `from` and `to` for explicit UTC date windows\n- Results are ordered newest first and support deterministic `offset` + `limit` pagination\n- supported tickers with no rows return `200` with `results=[]`\n- unsupported tickers return `404`, regardless of the requested window or offset","operationId":"getNewsStockMentions","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","pattern":"^(?=[A-Za-z0-9.]{1,32}$)[A-Za-z0-9]+(?:\\.(?:[Aa][Ee]|[Aa][Ss]|[Aa][Tt]|[Aa][Xx]|[Bb][Aa]|[Bb][Dd]|[Bb][Kk]|[Bb][Oo]|[Bb][Rr]|[Cc][Aa]|[Cc][Ll]|[Cc][Nn]|[Cc][Oo]|[Dd][Ee]|[Dd][Uu]|[Ff]|[Hh][Aa]|[Hh][Ee]|[Hh][Kk]|[Hh][Mm]|[Ii][Cc]|[Ii][Rr]|[Ii][Ss]|[Jj][Kk]|[Jj][Oo]|[Kk][Ll]|[Kk][Qq]|[Kk][Ss]|[Kk][Ww]|[Ll]|[Ll][Ss]|[Mm][Cc]|[Mm][Ii]|[Mm][Uu]|[Mm][Xx]|[Nn][Ee]|[Nn][Ss]|[Nn][Zz]|[Oo][Ll]|[Pp][Aa]|[Pp][Rr]|[Pp][Ss]|[Qq][Aa]|[Rr][Oo]|[Ss][Aa]|[Ss][Aa][Uu]|[Ss][Gg]|[Ss][Ii]|[Ss][Nn]|[Ss][Ss]|[Ss][Tt]|[Ss][Ww]|[Ss][Zz]|[Tt]|[Tt][Aa]|[Tt][Oo]|[Tt][Ww]|[Tt][Ww][Oo]|[Vv]|[Vv][Ii]|[Vv][Nn]|[Ww][Aa]))?$(?![\\s\\S])","description":"News company key: 1-32 ASCII letters/digits with an optional documented venue suffix, case-insensitive. Examples: BRK, EADSY, ABX.DE. Share classes (BRK.A, BRK.B, BRK-B), hyphens, ampersands, cashtags and unknown suffixes return 422. A documented suffix resolves only if assigned to that issuer; other well-formed keys return 404. One issuer is one time series; ETFs stay separate issuers. Venue suffixes: .AE, .AS, .AT, .AX, .BA, .BD, .BK, .BO, .BR, .CA, .CL, .CN, .CO, .DE, .DU, .F, .HA, .HE, .HK, .HM, .IC, .IR, .IS, .JK, .JO, .KL, .KQ, .KS, .KW, .L, .LS, .MC, .MI, .MU, .MX, .NE, .NS, .NZ, .OL, .PA, .PR, .PS, .QA, .RO, .SA, .SAU, .SG, .SI, .SN, .SS, .ST, .SW, .SZ, .T, .TA, .TO, .TW, .TWO, .V, .VI, .VN, .WA.","title":"Ticker"},"description":"News company key: 1-32 ASCII letters/digits with an optional documented venue suffix, case-insensitive. Examples: BRK, EADSY, ABX.DE. Share classes (BRK.A, BRK.B, BRK-B), hyphens, ampersands, cashtags and unknown suffixes return 422. A documented suffix resolves only if assigned to that issuer; other well-formed keys return 404. One issuer is one time series; ETFs stay separate issuers. Venue suffixes: .AE, .AS, .AT, .AX, .BA, .BD, .BK, .BO, .BR, .CA, .CL, .CN, .CO, .DE, .DU, .F, .HA, .HE, .HK, .HM, .IC, .IR, .IS, .JK, .JO, .KL, .KQ, .KS, .KW, .L, .LS, .MC, .MI, .MU, .MX, .NE, .NS, .NZ, .OL, .PA, .PR, .PS, .QA, .RO, .SA, .SAU, .SG, .SI, .SN, .SS, .ST, .SW, .SZ, .T, .TA, .TO, .TW, .TWO, .V, .VI, .VN, .WA."},{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date in YYYY-MM-DD. Inclusive UTC date.","title":"From"},"description":"Start date in YYYY-MM-DD. Inclusive UTC date."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date.","title":"To"},"description":"End date in YYYY-MM-DD. Inclusive UTC date. Omit to use the current UTC date."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of raw mentions to return","default":50,"title":"Limit"},"description":"Maximum number of raw mentions to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of raw mention rows to skip for offset-based pagination.","default":0,"title":"Offset"},"description":"Number of raw mention rows to skip for offset-based pagination."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewsRawMentionsResponse"},"example":{"ticker":"AAPL","period_days":7,"count":1,"results":[{"article_id":"news-123","source":"reuters","url":"https://example.com/article","title":"Apple supplier outlook lifts sentiment","summary":"Suppliers signaled stronger-than-expected demand...","text_snippet":"Suppliers signaled stronger-than-expected demand...","author":"Jane Doe","created_utc":"2026-03-20T09:03:00Z","sentiment_score":0.21,"sentiment_label":"positive"}]}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"private, max-age=60"},"Vary":{"description":"Headers that private client caches must include in their cache key.","schema":{"type":"string"},"example":"X-API-Key, Authorization, Accept-Encoding"},"X-RateLimit-Limit-Monthly":{"description":"Monthly request quota for the authenticated account.","schema":{"type":"string"},"example":"250"},"X-RateLimit-Remaining-Monthly":{"description":"Remaining monthly requests for the authenticated account.","schema":{"type":"string"},"example":"247"},"X-RateLimit-Used-Monthly":{"description":"Requests already consumed in the account's current monthly quota window.","schema":{"type":"string"},"example":"3"},"X-RateLimit-Reset-Monthly":{"description":"ISO 8601 timestamp when the current monthly quota window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-07-29T14:03:00Z"},"X-RateLimit-Limit-Burst":{"description":"Per-minute burst request quota for the authenticated account.","schema":{"type":"string"},"example":"100"},"X-RateLimit-Remaining-Burst":{"description":"Remaining requests in the current per-minute burst window.","schema":{"type":"string"},"example":"99"},"X-RateLimit-Reset-Burst":{"description":"ISO 8601 timestamp when the current burst rate-limit window resets.","schema":{"type":"string","format":"date-time"},"example":"2026-04-28T14:30:00Z"},"X-Account-Type":{"description":"Account tier resolved from the API key.","schema":{"type":"string","enum":["free","hobby","professional","premium"]},"example":"free"}}},"401":{"description":"Authentication failed","content":{"application/json":{"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Historical data limit exceeded","content":{"application/json":{"example":{"detail":{"error":"Historical data limit exceeded","message":"Your free account is limited to 30 days of historical lookback. Upgrade to Hobby for up to 90 days or Professional for up to 365 days: https://adanos.org/pricing","requested_days":60,"enforced_quantity":"lookback_days","max_days":30,"account_type":"free"}},"schema":{"$ref":"#/components/schemas/HistoricalLimitError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}},"schema":{"$ref":"#/components/schemas/RateLimitError"}}}},"422":{"description":"Invalid period or query parameters","content":{"application/json":{"examples":{"platform_availability":{"summary":"Period starts before platform data availability","value":{"detail":{"error":"Invalid period","message":"Requested period starts before this platform's public data availability.","period_from":"2025-03-17","available_since":"2026-03-07","platform":"news"}}},"validation":{"summary":"Query parameter validation failed","value":{"detail":[{"type":"date_from_datetime_parsing","loc":["query","from"],"msg":"Input should be a valid date or datetime, month value is outside expected range of 1-12","input":"2026-13-01","ctx":{"error":"month value is outside expected range of 1-12"}}]}}},"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidPeriodError"},{"$ref":"#/components/schemas/HTTPValidationError"}],"title":"Response 422 Getnewsstockmentions"}}}},"503":{"description":"News identity lookup or database service unavailable; no Legacy fallback is used","content":{"application/json":{"example":{"detail":"News identity lookup unavailable"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"504":{"description":"Analytics request deadline exceeded","content":{"application/json":{"example":{"detail":"Request deadline exceeded"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Unsupported ticker","content":{"application/json":{"example":{"detail":{"error_code":"unsupported_ticker","message":"Unsupported ticker $XYZ. This ticker is not supported by Adanos v1."}},"schema":{"$ref":"#/components/schemas/UnsupportedAssetError"}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/news/stocks/v1/stock/TSLA/mentions?from=2026-05-01&to=2026-05-07&limit=5\" \\\n  -H \"X-API-Key: $ADANOS_API_KEY\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/news/stocks/v1/stock/TSLA/mentions?from=2026-05-01&to=2026-05-07&limit=5\", {\n  headers: {\n    \"X-API-Key\": process.env.ADANOS_API_KEY,\n  },\n});\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import os\n\nimport requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/news/stocks/v1/stock/TSLA/mentions?from=2026-05-01&to=2026-05-07&limit=5\",\n    headers={\n        \"X-API-Key\": os.environ[\"ADANOS_API_KEY\"],\n    },\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/reddit/stocks/v1/health":{"get":{"tags":["Health-Check"],"summary":"Reddit Stocks health","description":"Shows whether Reddit Stocks data collection is running and when it last ran. No API key needed.\n\n`scheduler.last_scrape` is the time of the most recent collection. For data, use `/trending`, `/stock/{ticker}` or `/search`.","operationId":"getHealth","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"},"example":{"status":"healthy","service":"reddit-stocks","version":"1.53.4","total_mentions":12833,"tickers_tracked":65,"scheduler":{"running":true,"last_scrape":"2026-01-09T10:30:00Z","scrape_count":142,"error_count":3,"success_rate":0.979}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"no-store"}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/reddit/stocks/v1/health\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/reddit/stocks/v1/health\");\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/reddit/stocks/v1/health\",\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/reddit/crypto/v1/health":{"get":{"tags":["Health-Check"],"summary":"Reddit Crypto health","description":"Shows whether Reddit Crypto data collection is running and when it last ran. No API key needed.\n\n`scheduler.last_scrape` is the time of the most recent collection. For data, use `/trending`, `/token/{symbol}` or `/search`.","operationId":"getRedditCryptoHealth","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CryptoHealthResponse"},"example":{"status":"healthy","service":"reddit-crypto","version":"1.53.4","total_mentions":18352,"tokens_tracked":142,"scheduler":{"running":true,"last_scrape":"2026-03-12T07:55:00Z","scrape_count":248,"error_count":3,"success_rate":0.988,"timed_out_scrape_threads":0}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"no-store"}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/reddit/crypto/v1/health\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/reddit/crypto/v1/health\");\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/reddit/crypto/v1/health\",\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/x/stocks/v1/health":{"get":{"tags":["Health-Check"],"summary":"X/Twitter health","description":"Shows whether X/Twitter data collection is running and when it last ran. No API key needed.\n\n`scheduler.last_scrape` is the time of the most recent collection. For data, use `/trending`, `/stock/{ticker}` or `/search`.","operationId":"getXHealth","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/XHealthResponse"},"example":{"status":"healthy","service":"x-stocks","version":"1.53.4","total_mentions":15420,"tickers_tracked":247,"scheduler":{"running":true,"last_scrape":"2025-12-31T06:00:00Z","scrape_count":42,"error_count":2,"success_rate":0.95}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"no-store"}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/x/stocks/v1/health\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/x/stocks/v1/health\");\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/x/stocks/v1/health\",\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/polymarket/stocks/v1/health":{"get":{"tags":["Health-Check"],"summary":"Polymarket health","description":"Shows whether Polymarket data collection is running and when it last ran. No API key needed.\n\n`scheduler.last_scrape` is the time of the most recent collection. For data, use `/trending`, `/stock/{ticker}` or `/search`.","operationId":"getPolymarketHealth","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolymarketHealthResponse"},"example":{"status":"healthy","service":"polymarket-stocks","version":"1.53.4","total_mentions":8421,"tickers_tracked":119,"scheduler":{"running":true,"last_scrape":"2026-02-18T10:00:00Z","scrape_count":58,"error_count":1,"success_rate":0.983}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"no-store"}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/polymarket/stocks/v1/health\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/polymarket/stocks/v1/health\");\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/polymarket/stocks/v1/health\",\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/news/stocks/v1/health":{"get":{"tags":["Health-Check"],"summary":"News health","description":"Shows whether News data collection is running and when it last ran. No API key needed.\n\n`scheduler.last_scrape` is the time of the most recent collection. For data, use `/trending`, `/stock/{ticker}` or `/search`.","operationId":"getNewsHealth","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"},"example":{"status":"healthy","service":"reddit-stocks","version":"1.53.4","total_mentions":12833,"tickers_tracked":65,"scheduler":{"running":true,"last_scrape":"2026-01-09T10:30:00Z","scrape_count":142,"error_count":3,"success_rate":0.979}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"no-store"}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/news/stocks/v1/health\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/news/stocks/v1/health\");\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/news/stocks/v1/health\",\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/health":{"get":{"tags":["Health-Check"],"summary":"API health","description":"Checks the database and data collection for every platform in one call.\n\nNo API key needed. This check is slower than the per-platform `/health`\nendpoints, so poll those for routine monitoring.","operationId":"getRootHealth","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RootHealthResponse"},"example":{"status":"healthy","service":"adanos-api","version":"1.53.4","summary":{"total":5,"healthy":5,"unhealthy":0,"unhealthy_services":[]},"services":{"news-stocks":{"service":"news-stocks","status":"healthy","version":"1.53.4"},"polymarket-stocks":{"service":"polymarket-stocks","status":"healthy","version":"1.53.4"},"reddit-crypto":{"service":"reddit-crypto","status":"healthy","version":"1.53.4"},"reddit-stocks":{"service":"reddit-stocks","status":"healthy","version":"1.53.4"},"x-stocks":{"service":"x-stocks","status":"healthy","version":"1.53.4"}}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"},"Cache-Control":{"description":"HTTP cache policy returned by the API.","schema":{"type":"string"},"example":"no-store"}}},"503":{"description":"One or more platform checks failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RootHealthResponse"},"example":{"status":"healthy","service":"adanos-api","version":"1.53.4","summary":{"total":5,"healthy":5,"unhealthy":0,"unhealthy_services":[]},"services":{"news-stocks":{"service":"news-stocks","status":"healthy","version":"1.53.4"},"polymarket-stocks":{"service":"polymarket-stocks","status":"healthy","version":"1.53.4"},"reddit-crypto":{"service":"reddit-crypto","status":"healthy","version":"1.53.4"},"reddit-stocks":{"service":"reddit-stocks","status":"healthy","version":"1.53.4"},"x-stocks":{"service":"x-stocks","status":"healthy","version":"1.53.4"}}}}}}},"x-codeSamples":[{"lang":"curl","label":"cURL","source":"curl \"https://api.adanos.org/health\""},{"lang":"javascript","label":"JavaScript","source":"const response = await fetch(\"https://api.adanos.org/health\");\n\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst data = await response.json();\nconsole.log(data);"},{"lang":"python","label":"Python","source":"import requests\n\nresponse = requests.get(\n    \"https://api.adanos.org/health\",\n    timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())"}]}},"/sentiment/v1/analyze":{"post":{"tags":["Finance Sentiment"],"summary":"Analyze finance sentiment","description":"**Professional account required.** Free and Hobby accounts cannot use this endpoint.\n\nReturns the sentiment of one financial text, such as a news headline or a sentence about a company. Pass `target` (for example `Apple` or `AAPL`) to get the sentiment for that company. Scored by Adanos News Sentiment 5.5, our own model built for financial news.","operationId":"analyzeSentimentText","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SentimentAnalyzeRequest"},"example":{"text":"Apple beats earnings estimates and raises its dividend","target":"Apple"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SentimentAnalyzeResponse"},"example":{"text":"Apple beats earnings estimates and raises its dividend","sentiment_score":0.999,"sentiment_label":"positive","components":{"engine_version":"5.5","model_score":0.9988,"emoji_score":0.0,"phrase_adjustment":0.0,"phrase_matches":[],"contextual_finance_matches":[]}}}},"headers":{"X-Request-ID":{"description":"Request correlation identifier returned by the API and included in structured application logs.","schema":{"type":"string"},"example":"adnos.req-20260423.abc12345"}}},"401":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"missing":{"summary":"Missing API key","value":{"detail":"Missing API key. Include 'X-API-Key' header."}},"invalid":{"summary":"Invalid API key","value":{"detail":"Invalid API key."}},"revoked":{"summary":"Revoked API key","value":{"detail":"API key has been revoked."}}}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"},"examples":{"burst":{"summary":"Fleet burst limit exceeded","value":{"detail":{"error":"Burst rate limit exceeded","message":"Too many requests. Limit is 100 requests per minute.","limit":100,"used":100,"account_type":"free"}}},"local":{"summary":"Local backup limiter exceeded","value":{"detail":{"error":"Rate limit exceeded","message":"Rate limit exceeded: 100 per 1 minute","limit":100,"account_type":"free"}}}}}}},"503":{"description":"Sentiment inference service unavailable","headers":{"Retry-After":{"description":"Seconds clients should wait before retrying","schema":{"type":"integer","example":5}}},"content":{"application/json":{"example":{"detail":"Sentiment inference service unavailable."}}}},"422":{"description":"Request body validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"},"example":{"detail":[{"loc":["body","text"],"msg":"String should have at least 1 character","type":"string_too_short","input":"","ctx":{"min_length":1}}]}}}},"403":{"description":"Professional account required","content":{"application/json":{"example":{"detail":{"error":"Professional account required","message":"This endpoint requires a Professional account. Upgrade to Professional: https://adanos.org/pricing","account_type":"free"}}}}}},"security":[{"ApiKeyAuth":[]}]}}},"components":{"schemas":{"CompareLimitError":{"properties":{"detail":{"$ref":"#/components/schemas/CompareLimitErrorDetail","description":"Structured error details"}},"type":"object","required":["detail"],"title":"CompareLimitError","description":"Error response for compare item-count violations (HTTP 400)."},"CompareLimitErrorDetail":{"properties":{"error":{"type":"string","title":"Error","description":"Machine-readable error code"},"message":{"type":"string","title":"Message","description":"Human-readable error message"},"max_items":{"type":"integer","title":"Max Items","description":"Maximum accepted compare items"},"item_name":{"type":"string","title":"Item Name","description":"Compared item type, such as ticker or symbol"}},"type":"object","required":["error","message","max_items","item_name"],"title":"CompareLimitErrorDetail","description":"Structured error detail for compare item-count violations."},"CompareResponse":{"properties":{"period_days":{"type":"integer","title":"Period Days","description":"Analysis period in days","examples":[7]},"stocks":{"items":{"$ref":"#/components/schemas/CompareStockItem"},"type":"array","title":"Stocks","description":"Stocks sorted by buzz_score descending"}},"type":"object","required":["period_days","stocks"],"title":"CompareResponse","description":"Comparison of multiple stocks.","examples":[{"period_days":7,"stocks":[{"ticker":"TSLA","company_name":"Tesla, Inc.","buzz_score":87.5,"trend":"rising","mentions":342,"unique_posts":45,"subreddit_count":8,"sentiment_score":0.23,"bullish_pct":45,"bearish_pct":18,"total_upvotes":15234,"trend_history":[45.2,52.1,48.7,67.3,72.1,78.4,87.5]},{"ticker":"NVDA","company_name":"NVIDIA Corporation","buzz_score":72.3,"trend":"stable","mentions":189,"unique_posts":31,"subreddit_count":6,"sentiment_score":0.45,"bullish_pct":52,"bearish_pct":17,"total_upvotes":8921,"trend_history":[38.1,40.7,44.9,51.5,57.4,63.0,72.3]}]}]},"CompareStockItem":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol","examples":["TSLA"]},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name","description":"Company name","examples":["Tesla, Inc."]},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Buzz Score (0-100). Asymptotic scaling above 50.","examples":[87.5]},"trend":{"anyOf":[{"type":"string","enum":["rising","falling","stable"]},{"type":"null"}],"title":"Trend","description":"Activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today). Null when no qualifying Reddit data exists.","examples":["rising"]},"mentions":{"type":"integer","title":"Mentions","description":"Total attributed mentions in period, including inherited thread-context mentions","examples":[342]},"unique_posts":{"type":"integer","title":"Unique Posts","description":"Number of unique posts in period","examples":[45]},"subreddit_count":{"type":"integer","title":"Subreddit Count","description":"Number of subreddits with mentions in period","examples":[8]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average sentiment (-1 to +1, null if no mentions)","examples":[0.23]},"bullish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bullish Pct","description":"Percentage of bullish mentions","examples":[45]},"bearish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bearish Pct","description":"Percentage of bearish mentions","examples":[18]},"total_upvotes":{"type":"integer","title":"Total Upvotes","description":"Total upvotes from attributed mentions","examples":[15234]},"trend_history":{"items":{"type":"number"},"type":"array","title":"Trend History","description":"Daily buzz scores (oldest→newest). Length follows the resolved period, with a minimum of 7 values when data exists. Empty when no qualifying data exists.","examples":[[45.2,52.1,48.7,67.3,72.1,78.4,87.5]]}},"type":"object","required":["ticker","buzz_score","mentions","unique_posts","subreddit_count","total_upvotes"],"title":"CompareStockItem","description":"Individual stock in comparison."},"CryptoCompareResponse":{"properties":{"period_days":{"type":"integer","title":"Period Days","description":"Analysis period in days","examples":[7]},"tokens":{"items":{"$ref":"#/components/schemas/CryptoCompareTokenItem"},"type":"array","title":"Tokens","description":"Requested tokens sorted by buzz_score descending"}},"type":"object","required":["period_days","tokens"],"title":"CryptoCompareResponse","description":"Comparison response for multiple crypto symbols.","examples":[{"period_days":7,"tokens":[{"symbol":"BTC","name":"Bitcoin","buzz_score":78.1,"trend":"rising","mentions":423,"unique_posts":97,"subreddit_count":12,"sentiment_score":0.31,"bullish_pct":47,"bearish_pct":18,"total_upvotes":15620,"trend_history":[42.3,46.8,51.2,58.9,64.0,71.4,78.1]},{"symbol":"ETH","name":"Ethereum","buzz_score":72.4,"trend":"stable","mentions":318,"unique_posts":73,"subreddit_count":9,"sentiment_score":0.27,"bullish_pct":43,"bearish_pct":19,"total_upvotes":10422,"trend_history":[36.2,41.4,46.7,53.1,60.2,66.5,72.4]}]}]},"CryptoCompareTokenItem":{"properties":{"symbol":{"type":"string","title":"Symbol","examples":["BTC"]},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","examples":["Bitcoin"]},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","examples":[78.1]},"trend":{"anyOf":[{"type":"string","enum":["rising","falling","stable"]},{"type":"null"}],"title":"Trend","description":"Activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today). Null when no qualifying data exists.","examples":["rising"]},"mentions":{"type":"integer","title":"Mentions","description":"Attributed mentions in the selected period, including inherited thread-context mentions","examples":[423]},"unique_posts":{"type":"integer","title":"Unique Posts","description":"Unique Reddit post count","examples":[97]},"subreddit_count":{"type":"integer","title":"Subreddit Count","description":"Unique subreddit count","examples":[12]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","examples":[0.31]},"bullish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bullish Pct","examples":[47]},"bearish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bearish Pct","examples":[18]},"total_upvotes":{"type":"integer","title":"Total Upvotes","description":"Net upvotes (Reddit score) across attributed mentions; negative when downvotes prevail","examples":[15620]},"trend_history":{"items":{"type":"number"},"type":"array","title":"Trend History","description":"Daily buzz scores (oldest to newest). Length follows the resolved period, with a minimum of 7 values when data exists. Empty when no qualifying data exists.","examples":[[42.3,46.8,51.2,58.9,64.0,71.4,78.1]]}},"type":"object","required":["symbol","buzz_score","mentions","unique_posts","subreddit_count","total_upvotes"],"title":"CryptoCompareTokenItem","description":"Individual crypto token in a compare response."},"CryptoDailyTrendItem":{"properties":{"date":{"type":"string","format":"date","title":"Date","description":"Date in YYYY-MM-DD format","examples":["2026-02-24"]},"mentions":{"type":"integer","title":"Mentions","description":"Attributed mention count for the day, including inherited thread-context mentions","examples":[84]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average sentiment score for the day","examples":[0.22]},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Buzz score for this date (0-100); null until the day is aggregated, while the activity fields are already filled","examples":[56.4]},"bullish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bullish Pct","description":"Bullish mention percentage for the day, calculated from positive sentiment-classified mentions","examples":[58]},"bearish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bearish Pct","description":"Bearish mention percentage for the day, calculated from negative sentiment-classified mentions","examples":[22]}},"type":"object","required":["date","mentions"],"title":"CryptoDailyTrendItem","description":"Daily trend datapoint for a crypto symbol."},"CryptoHealthResponse":{"properties":{"status":{"type":"string","title":"Status","examples":["healthy"]},"service":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Service","examples":["reddit-crypto"]},"version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Version","examples":["1.53.4"]},"total_mentions":{"type":"integer","title":"Total Mentions","description":"Mentions observed in the most recent scrape cycle; returns 0 when scrape telemetry is unavailable.","default":0},"tokens_tracked":{"type":"integer","title":"Tokens Tracked","description":"Distinct symbols observed in the most recent scrape cycle; returns 0 when scrape telemetry is unavailable.","default":0},"scheduler":{"anyOf":[{"$ref":"#/components/schemas/CryptoSchedulerStatus"},{"type":"null"}]},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"}},"type":"object","required":["status"],"title":"CryptoHealthResponse","description":"Health response for Reddit Crypto service.","examples":[{"status":"healthy","service":"reddit-crypto","version":"1.53.4","total_mentions":18352,"tokens_tracked":142,"scheduler":{"running":true,"last_scrape":"2026-03-12T07:55:00Z","scrape_count":248,"error_count":3,"success_rate":0.988,"timed_out_scrape_threads":0}}]},"CryptoMarketSentimentDriver":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"Crypto symbol","examples":["BTC"]},"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"Attributed Reddit mentions in the selected period, including inherited thread-context mentions","examples":[423]},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Asset buzz score in the selected period","examples":[78.1]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average sentiment score for this asset","examples":[0.31]}},"type":"object","required":["symbol","mentions","buzz_score"],"title":"CryptoMarketSentimentDriver","description":"Top asset contributing to the service-level Reddit Crypto market sentiment."},"CryptoMarketSentimentResponse":{"properties":{"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Service-wide Reddit Crypto heat score relative to the trailing 90-day baseline for the selected period","examples":[52.4]},"trend":{"anyOf":[{"type":"string","enum":["rising","falling","stable"]},{"type":"null"}],"title":"Trend","description":"Activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["rising"]},"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"Total Reddit mentions across the selected period, including inherited thread-context mentions","examples":[5412]},"unique_posts":{"type":"integer","minimum":0.0,"title":"Unique Posts","description":"Exact distinct Reddit post count across the selected UTC period","examples":[1184]},"subreddit_count":{"type":"integer","minimum":0.0,"title":"Subreddit Count","description":"Distinct subreddits contributing in the selected period","examples":[37]},"total_upvotes":{"type":"integer","minimum":0.0,"title":"Total Upvotes","description":"Total upvotes across attributed mentions in the selected period","examples":[41290]},"active_tickers":{"type":"integer","minimum":0.0,"title":"Active Tickers","description":"Number of crypto symbols with activity in the selected period","examples":[89]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Service-wide average sentiment score across the selected period","examples":[0.117]},"positive_count":{"type":"integer","minimum":0.0,"title":"Positive Count","description":"Deprecated. Prefer bullish_pct with mentions for public analysis; retained for v1 compatibility.","deprecated":true,"examples":[2101]},"negative_count":{"type":"integer","minimum":0.0,"title":"Negative Count","description":"Deprecated. Prefer bearish_pct with mentions for public analysis; retained for v1 compatibility.","deprecated":true,"examples":[1318]},"neutral_count":{"type":"integer","minimum":0.0,"title":"Neutral Count","description":"Deprecated. Prefer bullish_pct, bearish_pct and mentions for public analysis; retained for v1 compatibility.","deprecated":true,"examples":[1993]},"bullish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bullish Pct","description":"Bullish mention percentage","examples":[39]},"bearish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bearish Pct","description":"Bearish mention percentage","examples":[24]},"trend_history":{"items":{"type":"number"},"type":"array","title":"Trend History","description":"Daily service-wide Reddit Crypto heat scores (oldest→newest), each calibrated relative to the trailing 90-day baseline. Length = max(requested_days, 7) for successful requests; windows before platform availability return HTTP 422.","examples":[[47.1,49.3,50.4,52.2,51.8,53.0,52.4]]},"drivers":{"items":{"$ref":"#/components/schemas/CryptoMarketSentimentDriver"},"type":"array","title":"Drivers","description":"Top 5 tokens of the selected period by buzz_score. mentions and sentiment_score cover every day of the period."}},"type":"object","required":["buzz_score","mentions","unique_posts","subreddit_count","total_upvotes","active_tickers","positive_count","negative_count","neutral_count","bullish_pct","bearish_pct"],"title":"CryptoMarketSentimentResponse","description":"Service-level Reddit Crypto market sentiment across all tracked assets.","examples":[{"buzz_score":52.4,"trend":"stable","mentions":5412,"unique_posts":1184,"subreddit_count":37,"total_upvotes":41290,"active_tickers":89,"sentiment_score":0.117,"positive_count":2101,"negative_count":1318,"neutral_count":1993,"bullish_pct":39,"bearish_pct":24,"trend_history":[47.1,49.3,50.4,52.2,51.8,53.0,52.4],"drivers":[{"symbol":"BTC","mentions":423,"buzz_score":78.1,"sentiment_score":0.31},{"symbol":"ETH","mentions":318,"buzz_score":72.4,"sentiment_score":0.27}]}]},"CryptoRawMentionItem":{"properties":{"post_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Post Id","description":"Reddit post identifier","examples":["abc123"]},"comment_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Comment Id","description":"Reddit comment identifier when the mention comes from a comment","examples":["def456"]},"subreddit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subreddit","description":"Source subreddit","examples":["cryptocurrency"]},"author":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author","description":"Public Reddit author name, if scraped","examples":["deepfuckingvalue"]},"text_snippet":{"type":"string","title":"Text Snippet","description":"Stored mention snippet (truncated at ingestion time)","examples":["BTC still looks strong above this range..."]},"created_utc":{"type":"string","format":"date-time","title":"Created Utc","description":"UTC timestamp of creation (ISO 8601)","examples":["2026-03-20T18:42:10Z"]},"upvotes":{"type":"integer","title":"Upvotes","description":"Reddit score (upvotes) for this mention row","examples":[381]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Sentiment score (-1 to +1)","examples":[0.62]},"sentiment_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sentiment Label","description":"Sentiment label (positive/negative/neutral)","examples":["positive"]},"is_inherited":{"type":"boolean","title":"Is Inherited","description":"Whether symbol context was inherited from the parent thread instead of directly mentioned","examples":[false]}},"type":"object","required":["text_snippet","created_utc","upvotes","is_inherited"],"title":"CryptoRawMentionItem","description":"Raw Reddit crypto mention row for one symbol."},"CryptoRawMentionsResponse":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"Crypto symbol","examples":["BTC"]},"period_days":{"type":"integer","minimum":1.0,"title":"Period Days","description":"Lookback window used for the query","examples":[7]},"count":{"type":"integer","minimum":0.0,"title":"Count","description":"Total number of matching raw rows for the requested include_inherited filter before limit and offset are applied; only the requested page is returned","examples":[1]},"results":{"items":{"$ref":"#/components/schemas/CryptoRawMentionItem"},"type":"array","title":"Results","description":"Raw mention rows ordered by newest first"}},"type":"object","required":["symbol","period_days","count","results"],"title":"CryptoRawMentionsResponse","description":"Paginated raw Reddit crypto mentions for a single symbol.","examples":[{"symbol":"BTC","period_days":7,"count":1,"results":[{"post_id":"abc123","comment_id":"def456","subreddit":"cryptocurrency","author":"user123","text_snippet":"BTC still looks strong above this range...","created_utc":"2026-03-20T18:42:10Z","upvotes":381,"sentiment_score":0.62,"sentiment_label":"positive","is_inherited":false}]}]},"CryptoSchedulerStatus":{"properties":{"running":{"type":"boolean","title":"Running","description":"Whether data collection is running"},"last_scrape":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Scrape","description":"Last scrape timestamp"},"scrape_count":{"type":"integer","title":"Scrape Count","description":"Total scrapes","default":0},"error_count":{"type":"integer","title":"Error Count","description":"Total failed scrapes","default":0},"success_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Success Rate","description":"Success ratio"},"timed_out_scrape_threads":{"type":"integer","title":"Timed Out Scrape Threads","description":"Timed-out collection attempts since the last successful reset.","default":0},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note","description":"Additional status information"}},"type":"object","required":["running"],"title":"CryptoSchedulerStatus","description":"Reddit Crypto data collection status."},"CryptoSearchItem":{"properties":{"symbol":{"type":"string","title":"Symbol","examples":["SOL"]},"name":{"type":"string","title":"Name","examples":["Solana"]},"market_cap_rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Market Cap Rank","examples":[6]},"market_cap_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Market Cap Usd","examples":[71234567890.12]},"aliases":{"items":{"type":"string"},"type":"array","title":"Aliases","examples":[["Sol"]]},"summary":{"$ref":"#/components/schemas/CryptoSearchSummary","description":"Last-7-days Reddit summary for this asset"}},"type":"object","required":["symbol","name","summary"],"title":"CryptoSearchItem","description":"Single search result for crypto reference data."},"CryptoSearchResponse":{"properties":{"query":{"type":"string","title":"Query","description":"Original search query","examples":["solana"]},"count":{"type":"integer","title":"Count","description":"Total number of matching assets before the limit is applied","examples":[1]},"period_days":{"type":"integer","minimum":1.0,"title":"Period Days","description":"Fixed lookback window used for each summary block","examples":[7]},"results":{"items":{"$ref":"#/components/schemas/CryptoSearchItem"},"type":"array","title":"Results","description":"Top matching crypto assets capped by the requested limit"}},"type":"object","required":["query","count","period_days","results"],"title":"CryptoSearchResponse","description":"Search response for crypto assets.","examples":[{"query":"solana","count":1,"period_days":7,"results":[{"symbol":"SOL","name":"Solana","market_cap_rank":6,"market_cap_usd":71234567890.12,"aliases":["Sol"],"summary":{"mentions":287,"buzz_score":72.4,"trend":"stable","sentiment_score":0.27,"bearish_pct":19,"bullish_pct":43,"subreddit_count":9,"total_upvotes":10422,"unique_posts":73}}]}]},"CryptoSearchSummary":{"properties":{"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"Attributed mentions in the last 7 UTC calendar days, including inherited thread-context mentions","examples":[287]},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Buzz score over the last 7 UTC calendar days","examples":[72.4]},"trend":{"anyOf":[{"type":"string","enum":["rising","falling","stable"]},{"type":"null"}],"title":"Trend","description":"Activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["stable"]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average sentiment score over the last 7 UTC calendar days","examples":[0.27]}},"type":"object","required":["mentions","buzz_score"],"title":"CryptoSearchSummary","description":"Compact last-7-days summary attached to crypto search results."},"CryptoStatsResponse":{"properties":{"total_mentions":{"type":"integer","title":"Total Mentions","description":"All-time number of stored Reddit Crypto mentions","examples":[18352]},"unique_tokens":{"type":"integer","title":"Unique Tokens","examples":[142]},"mentions_today":{"type":"integer","title":"Mentions Today","default":0,"examples":[287]},"unique_tokens_today":{"type":"integer","title":"Unique Tokens Today","default":0,"examples":[35]},"supported_tokens":{"type":"integer","title":"Supported Tokens","examples":[500]}},"type":"object","required":["total_mentions","unique_tokens","supported_tokens"],"title":"CryptoStatsResponse","description":"High-level crypto dataset statistics.","examples":[{"total_mentions":18352,"unique_tokens":142,"mentions_today":287,"unique_tokens_today":35,"supported_tokens":500}]},"CryptoSubredditCount":{"properties":{"subreddit":{"type":"string","title":"Subreddit","description":"Subreddit name","examples":["cryptocurrency"]},"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"Attributed mentions in this subreddit","examples":[89]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average sentiment score for this subreddit in the selected period","examples":[0.22]},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Contributor-level buzz score for this subreddit in the selected period","examples":[61.5]},"count":{"type":"integer","minimum":0.0,"title":"Count","description":"Deprecated alias for mentions. Use mentions instead.","deprecated":true,"examples":[89]}},"type":"object","required":["subreddit","mentions","count"],"title":"CryptoSubredditCount","description":"Subreddit contributor metrics for a crypto detail response."},"CryptoTokenSentiment":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"Token symbol","examples":["ETH"]},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Token name","examples":["Ethereum"]},"found":{"type":"boolean","title":"Found","description":"Legacy v1 data-availability flag. `true` means this service has qualifying data for this asset/window. `false` means the asset is supported, but this service has no qualifying data for the requested window. Planned for removal in v2.","deprecated":true},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Buzz score"},"mentions":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Mentions","description":"Attributed mentions in the selected period, including inherited thread-context mentions","examples":[318]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average sentiment"},"positive_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Positive Count","description":"Deprecated. Prefer bullish_pct with mentions for public analysis; retained for v1 compatibility.","deprecated":true},"negative_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Negative Count","description":"Deprecated. Prefer bearish_pct with mentions for public analysis; retained for v1 compatibility.","deprecated":true},"neutral_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Neutral Count","description":"Deprecated. Prefer bullish_pct, bearish_pct and mentions for public analysis; retained for v1 compatibility.","deprecated":true},"total_upvotes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Upvotes","description":"Net upvotes (Reddit score) across attributed mentions; negative when downvotes prevail"},"unique_posts":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Unique Posts","description":"Distinct post count"},"subreddit_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Subreddit Count","description":"Distinct subreddit count"},"trend":{"anyOf":[{"type":"string","enum":["rising","falling","stable"]},{"type":"null"}],"title":"Trend","description":"Activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)."},"bullish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bullish Pct","description":"Bullish mention percentage"},"bearish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bearish Pct","description":"Bearish mention percentage"},"period_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Period Days","description":"Analysis period in days"},"top_subreddits":{"anyOf":[{"items":{"$ref":"#/components/schemas/CryptoSubredditCount"},"type":"array"},{"type":"null"}],"title":"Top Subreddits","description":"Top subreddits by mentions"},"daily_trend":{"anyOf":[{"items":{"$ref":"#/components/schemas/CryptoDailyTrendItem"},"type":"array"},{"type":"null"}],"title":"Daily Trend","description":"Daily attributed mention breakdown for the selected period, with sentiment and buzz_score"},"top_mentions":{"anyOf":[{"items":{"$ref":"#/components/schemas/CryptoTopMention"},"type":"array"},{"type":"null"}],"title":"Top Mentions","description":"Top explicit mentions from the selected period, ranked by engagement"}},"type":"object","required":["symbol","found"],"title":"CryptoTokenSentiment","description":"Detailed Reddit sentiment for a single crypto symbol.","examples":[{"symbol":"ETH","name":"Ethereum","found":true,"buzz_score":72.4,"mentions":318,"sentiment_score":0.27,"total_upvotes":10422,"unique_posts":73,"subreddit_count":9,"trend":"stable","bullish_pct":43,"bearish_pct":19,"period_days":7,"top_subreddits":[{"subreddit":"ethtrader","mentions":91,"count":91},{"subreddit":"cryptocurrency","mentions":84,"count":84}],"daily_trend":[{"date":"2026-02-24","mentions":48,"sentiment_score":0.22,"buzz_score":56.4,"bullish_pct":58,"bearish_pct":21},{"date":"2026-02-23","mentions":42,"sentiment_score":0.19,"buzz_score":51.7,"bullish_pct":52,"bearish_pct":24}],"top_mentions":[{"text_snippet":"ETH setup still looks strong into the next catalyst.","sentiment_score":0.74,"sentiment_label":"positive","upvotes":1200,"subreddit":"ethtrader","created_utc":"2026-02-24T09:15:00Z"}]}]},"CryptoTopMention":{"properties":{"text_snippet":{"type":"string","title":"Text Snippet","description":"Mention text snippet"},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Sentiment score (-1 to +1)"},"sentiment_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sentiment Label","description":"Sentiment label"},"upvotes":{"type":"integer","title":"Upvotes","description":"Upvote count","examples":[1200]},"subreddit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subreddit","description":"Source subreddit","examples":["cryptocurrency"]},"created_utc":{"type":"string","format":"date-time","title":"Created Utc","description":"UTC timestamp of creation (ISO 8601)"}},"type":"object","required":["text_snippet","upvotes","created_utc"],"title":"CryptoTopMention","description":"Top Reddit mention ordered by engagement."},"CryptoTrendingToken":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"Token symbol","examples":["BTC"]},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Token name","examples":["Bitcoin"]},"buzz_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Buzz Score","description":"Buzz score (0-100)","examples":[78.1]},"trend":{"type":"string","enum":["rising","falling","stable"],"title":"Trend","description":"Activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)."},"mentions":{"type":"integer","title":"Mentions","description":"Attributed mention count, including inherited thread-context mentions","examples":[423]},"unique_posts":{"type":"integer","title":"Unique Posts","description":"Unique Reddit post count","examples":[97]},"subreddit_count":{"type":"integer","title":"Subreddit Count","description":"Unique subreddit count","examples":[12]},"sentiment_score":{"type":"number","maximum":1.0,"minimum":-1.0,"title":"Sentiment Score","description":"Average sentiment score","examples":[0.31]},"bullish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bullish Pct","description":"Bullish mention percentage","examples":[47]},"bearish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bearish Pct","description":"Bearish mention percentage","examples":[18]},"total_upvotes":{"type":"integer","title":"Total Upvotes","description":"Net upvotes (Reddit score) across attributed mentions; negative when downvotes prevail","examples":[15620]},"trend_history":{"items":{"type":"number"},"type":"array","title":"Trend History","description":"Daily buzz scores (oldest to newest). Length follows the resolved period, with a minimum of 7 values."}},"type":"object","required":["symbol","buzz_score","trend","mentions","unique_posts","subreddit_count","sentiment_score","bullish_pct","bearish_pct","total_upvotes"],"title":"CryptoTrendingToken","description":"Trending crypto token summary.","examples":[{"symbol":"BTC","name":"Bitcoin","buzz_score":78.1,"trend":"rising","mentions":423,"unique_posts":97,"subreddit_count":12,"sentiment_score":0.31,"bullish_pct":47,"bearish_pct":18,"total_upvotes":15620,"trend_history":[42.3,46.8,51.2,58.9,64.0,71.4,78.1]}]},"DailyTrendItem":{"properties":{"date":{"type":"string","format":"date","title":"Date","description":"Date in YYYY-MM-DD format","examples":["2025-12-28"]},"mentions":{"type":"integer","title":"Mentions","description":"Attributed mention count for this date, including inherited thread-context mentions","examples":[52]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average sentiment score for this date","examples":[0.31]},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Buzz score for this date (0-100); null until the day is aggregated, while the activity fields are already filled","examples":[42.8]},"bullish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bullish Pct","description":"Bullish mention percentage for this date, calculated from positive sentiment-classified mentions","examples":[62]},"bearish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bearish Pct","description":"Bearish mention percentage for this date, calculated from negative sentiment-classified mentions","examples":[18]}},"type":"object","required":["date","mentions"],"title":"DailyTrendItem","description":"Daily trend data point."},"ErrorResponse":{"properties":{"detail":{"type":"string","title":"Detail","description":"Human-readable error message","examples":["Invalid API key."]}},"type":"object","required":["detail"],"title":"ErrorResponse","description":"Standard error response.","examples":[{"detail":"Missing API key. Include 'X-API-Key' header."},{"detail":"Invalid API key."},{"detail":"API key has been revoked."},{"detail":"Rate limit exceeded: 100 per 1 minute"}]},"HTTPValidationError":{"properties":{"detail":{"anyOf":[{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array"},{"type":"null"}],"title":"Detail","description":"Validation error details"}},"type":"object","title":"HTTPValidationError","description":"FastAPI/Pydantic validation error response.","examples":[{"detail":[{"loc":["query","limit"],"msg":"Input should be greater than or equal to 1","type":"greater_than_equal"}]}]},"HealthResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Current health status","examples":["healthy"]},"service":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Service","description":"Service identifier","examples":["reddit-stocks"]},"version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Version","description":"Service version","examples":["1.53.4"]},"total_mentions":{"type":"integer","title":"Total Mentions","description":"Mentions observed in the most recent scrape cycle; returns 0 when scrape telemetry is unavailable.","default":0,"examples":[12833]},"tickers_tracked":{"type":"integer","title":"Tickers Tracked","description":"Distinct tickers observed in the most recent scrape cycle; returns 0 when scrape telemetry is unavailable.","default":0,"examples":[65]},"scheduler":{"anyOf":[{"$ref":"#/components/schemas/SchedulerStatus"},{"type":"null"}],"description":"Scheduler status information"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message if unhealthy"}},"type":"object","required":["status"],"title":"HealthResponse","description":"API health status.","examples":[{"status":"healthy","service":"reddit-stocks","version":"1.53.4","total_mentions":12833,"tickers_tracked":65,"scheduler":{"running":true,"last_scrape":"2026-01-09T10:30:00Z","scrape_count":142,"error_count":3,"success_rate":0.979}}]},"HistoricalLimitError":{"properties":{"detail":{"$ref":"#/components/schemas/HistoricalLimitErrorDetail","description":"Structured error details"}},"type":"object","required":["detail"],"title":"HistoricalLimitError","description":"Error response for historical data limit exceeded (HTTP 403)."},"HistoricalLimitErrorDetail":{"properties":{"error":{"type":"string","title":"Error","description":"Error type identifier"},"message":{"type":"string","title":"Message","description":"Human-readable error message"},"requested_days":{"type":"integer","title":"Requested Days","description":"Number of days requested"},"enforced_quantity":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Enforced Quantity","description":"Quantity checked against the account tier limit"},"max_days":{"type":"integer","title":"Max Days","description":"Maximum days allowed for account tier"},"account_type":{"type":"string","title":"Account Type","description":"User's account type (free, hobby, professional, premium)"}},"type":"object","required":["error","message","requested_days","max_days","account_type"],"title":"HistoricalLimitErrorDetail","description":"Structured error detail for historical data limit exceeded."},"InvalidPeriodError":{"properties":{"detail":{"$ref":"#/components/schemas/InvalidPeriodErrorDetail","description":"Structured error details"}},"type":"object","required":["detail"],"title":"InvalidPeriodError","description":"Error response for invalid period requests (HTTP 422)."},"InvalidPeriodErrorDetail":{"properties":{"error":{"type":"string","title":"Error","description":"Error type identifier"},"message":{"type":"string","title":"Message","description":"Human-readable error message"},"field":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Field","description":"Invalid query parameter name"},"value":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"null"}],"title":"Value","description":"Invalid query parameter value"},"today":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Today","description":"Current UTC date used for validation"},"period_from":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Period From","description":"Resolved inclusive UTC start date"},"period_to":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Period To","description":"Resolved inclusive UTC end date"},"available_since":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Available Since","description":"Earliest public data date for the platform"},"retention_from":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Retention From","description":"Earliest date retained for the endpoint"},"requested_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Requested Days","description":"Number of days requested"},"max_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Days","description":"Maximum days accepted by the endpoint"},"platform":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Platform","description":"Platform identifier"}},"type":"object","required":["error","message"],"title":"InvalidPeriodErrorDetail","description":"Structured error detail for invalid period windows."},"InvalidSearchParametersError":{"properties":{"detail":{"anyOf":[{"$ref":"#/components/schemas/InvalidSearchParametersErrorDetail"},{"type":"string"}],"title":"Detail","description":"Structured search-parameter error or normalized-query validation message"}},"type":"object","required":["detail"],"title":"InvalidSearchParametersError","description":"Error response for invalid search query parameters."},"InvalidSearchParametersErrorDetail":{"properties":{"error":{"type":"string","title":"Error","description":"Error type identifier"},"message":{"type":"string","title":"Message","description":"Human-readable error message"},"unsupported_parameters":{"items":{"type":"string"},"type":"array","title":"Unsupported Parameters","description":"Search query parameters that are not supported"}},"type":"object","required":["error","message","unsupported_parameters"],"title":"InvalidSearchParametersErrorDetail","description":"Structured error detail for unsupported search query parameters."},"NewsCompareResponse":{"properties":{"period_days":{"type":"integer","title":"Period Days","description":"Analysis period in days","examples":[7]},"stocks":{"items":{"$ref":"#/components/schemas/NewsCompareStockItem"},"type":"array","title":"Stocks","description":"Stocks sorted by buzz_score descending"}},"type":"object","required":["period_days","stocks"],"title":"NewsCompareResponse","description":"Comparison of multiple stocks in news.","examples":[{"period_days":7,"stocks":[{"ticker":"TSLA","company_name":"Tesla, Inc.","buzz_score":87.5,"trend":"rising","mentions":342,"source_count":8,"sentiment_score":0.23,"bullish_pct":45,"bearish_pct":18,"trend_history":[45.2,52.1,48.7,67.3,72.1,78.4,87.5]},{"ticker":"NVDA","company_name":"NVIDIA Corporation","buzz_score":72.3,"trend":"stable","mentions":189,"source_count":6,"sentiment_score":0.45,"bullish_pct":51,"bearish_pct":16,"trend_history":[36.5,41.2,46.8,53.4,60.3,66.1,72.3]}]}]},"NewsCompareStockItem":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol","examples":["TSLA"]},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name","description":"Company or fund name from resolved instrument metadata or the Legacy reference","examples":["Tesla, Inc."]},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Buzz Score (0-100). Asymptotic scaling above 50.","examples":[87.5]},"trend":{"anyOf":[{"type":"string","enum":["rising","falling","stable"]},{"type":"null"}],"title":"Trend","description":"Activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions/articles and source breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today). Null when no qualifying news data exists.","examples":["rising"]},"mentions":{"type":"integer","title":"Mentions","description":"Total mentions in period","examples":[342]},"source_count":{"type":"integer","title":"Source Count","description":"Number of distinct news sources with mentions in period","examples":[8]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average sentiment (-1 to +1, null if no mentions)","examples":[0.23]},"bullish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bullish Pct","description":"Percentage of bullish mentions","examples":[45]},"bearish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bearish Pct","description":"Percentage of bearish mentions","examples":[18]},"trend_history":{"items":{"type":"number"},"type":"array","title":"Trend History","description":"Daily buzz scores (oldest→newest). Length follows the resolved period, with a minimum of 7 values when data exists. Empty when no qualifying data exists.","examples":[[45.2,52.1,48.7,67.3,72.1,78.4,87.5]]}},"type":"object","required":["ticker","buzz_score","mentions","source_count"],"title":"NewsCompareStockItem","description":"Individual stock in news comparison."},"NewsMarketSentimentDriver":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol","examples":["AAPL"]},"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"News mentions in the selected period","examples":[87]},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Asset buzz score in the selected period","examples":[69.7]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average news sentiment score for this asset","examples":[0.22]}},"type":"object","required":["ticker","mentions","buzz_score"],"title":"NewsMarketSentimentDriver","description":"Top asset contributing to the service-level News market sentiment."},"NewsMarketSentimentResponse":{"properties":{"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Service-wide News heat score relative to the service's trailing 90-day baseline. Around 50 = normal coverage heat, higher values = hotter-than-usual coverage.","examples":[53.8]},"trend":{"anyOf":[{"type":"string","enum":["rising","falling","stable"]},{"type":"null"}],"title":"Trend","description":"Activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions/articles and source breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["stable"]},"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"News mentions across the selected period","examples":[1298]},"unique_articles":{"type":"integer","minimum":0.0,"title":"Unique Articles","description":"Exact distinct article count across the selected UTC period","examples":[911]},"source_count":{"type":"integer","minimum":0.0,"title":"Source Count","description":"Exact distinct news-source breadth across the selected UTC period","examples":[44]},"active_tickers":{"type":"integer","minimum":0.0,"title":"Active Tickers","description":"Number of tickers with news activity in the selected period","examples":[233]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Service-wide average news sentiment score","examples":[0.064]},"positive_count":{"type":"integer","minimum":0.0,"title":"Positive Count","description":"Deprecated. Prefer bullish_pct with mentions for public analysis; retained for v1 compatibility.","deprecated":true,"examples":[512]},"negative_count":{"type":"integer","minimum":0.0,"title":"Negative Count","description":"Deprecated. Prefer bearish_pct with mentions for public analysis; retained for v1 compatibility.","deprecated":true,"examples":[308]},"neutral_count":{"type":"integer","minimum":0.0,"title":"Neutral Count","description":"Deprecated. Prefer bullish_pct, bearish_pct and mentions for public analysis; retained for v1 compatibility.","deprecated":true,"examples":[478]},"bullish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bullish Pct","description":"Bullish news mention percentage","examples":[39]},"bearish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bearish Pct","description":"Bearish news mention percentage","examples":[24]},"trend_history":{"items":{"type":"number"},"type":"array","title":"Trend History","description":"Daily service-wide buzz scores (oldest→newest) using the same relative baseline calibration. Length = max(requested_days, 7) for successful requests; windows before platform availability return HTTP 422.","examples":[[49.1,50.4,48.7,52.2,55.1,54.3,53.8]]},"drivers":{"items":{"$ref":"#/components/schemas/NewsMarketSentimentDriver"},"type":"array","title":"Drivers","description":"Top assets by current buzz_score driving the service-level reading"}},"type":"object","required":["buzz_score","mentions","unique_articles","source_count","active_tickers","positive_count","negative_count","neutral_count","bullish_pct","bearish_pct"],"title":"NewsMarketSentimentResponse","description":"Service-level News market sentiment across all tracked stocks.","examples":[{"buzz_score":53.8,"trend":"stable","mentions":1298,"unique_articles":911,"source_count":44,"active_tickers":233,"sentiment_score":0.064,"positive_count":512,"negative_count":308,"neutral_count":478,"bullish_pct":39,"bearish_pct":24,"trend_history":[49.1,50.4,48.7,52.2,55.1,54.3,53.8],"drivers":[{"ticker":"AAPL","mentions":87,"buzz_score":69.7,"sentiment_score":0.22},{"ticker":"NVDA","mentions":76,"buzz_score":67.3,"sentiment_score":0.31}]}]},"NewsRawMentionItem":{"properties":{"article_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Article Id","description":"Article identifier when available","examples":["news-123"]},"source":{"type":"string","title":"Source","description":"Source publication identifier","examples":["reuters"]},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"Article URL","examples":["https://example.com/article"]},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Article title","examples":["Apple supplier outlook lifts sentiment"]},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Summary","description":"Article summary","examples":["Suppliers signaled stronger-than-expected demand..."]},"text_snippet":{"type":"string","title":"Text Snippet","description":"Stored article snippet (truncated at ingestion time)","examples":["Suppliers signaled stronger-than-expected demand..."]},"author":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author","description":"Public article author/byline when available","examples":["Jane Doe"]},"created_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created Utc","description":"ISO timestamp of creation when available","examples":["2026-03-20T09:03:00Z"]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Sentiment score (-1 to +1)","examples":[0.21]},"sentiment_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sentiment Label","description":"Sentiment label (positive/negative/neutral)","examples":["positive"]}},"type":"object","required":["source","text_snippet"],"title":"NewsRawMentionItem","description":"Raw news mention row for one stock ticker."},"NewsRawMentionsResponse":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol","examples":["AAPL"]},"period_days":{"type":"integer","minimum":1.0,"title":"Period Days","description":"Lookback window used for the query","examples":[7]},"count":{"type":"integer","minimum":0.0,"title":"Count","description":"Total number of matching raw rows before limit and offset are applied; only the requested page is returned","examples":[1]},"results":{"items":{"$ref":"#/components/schemas/NewsRawMentionItem"},"type":"array","title":"Results","description":"Raw news mention rows ordered by newest first"}},"type":"object","required":["ticker","period_days","count","results"],"title":"NewsRawMentionsResponse","description":"Paginated raw news mentions for a single stock ticker.","examples":[{"ticker":"AAPL","period_days":7,"count":1,"results":[{"article_id":"news-123","source":"reuters","url":"https://example.com/article","title":"Apple supplier outlook lifts sentiment","summary":"Suppliers signaled stronger-than-expected demand...","text_snippet":"Suppliers signaled stronger-than-expected demand...","author":"Jane Doe","created_utc":"2026-03-20T09:03:00Z","sentiment_score":0.21,"sentiment_label":"positive"}]}]},"NewsSearchResponse":{"properties":{"query":{"type":"string","title":"Query","description":"Original search query","examples":["tesla"]},"count":{"type":"integer","title":"Count","description":"Total number of matching results before the limit is applied","examples":[1]},"period_days":{"type":"integer","minimum":1.0,"title":"Period Days","description":"Fixed lookback window used for each summary block","examples":[7]},"results":{"items":{"$ref":"#/components/schemas/NewsSearchResultItem"},"type":"array","title":"Results","description":"Top matching stocks capped by the requested limit"}},"type":"object","required":["query","count","period_days","results"],"title":"NewsSearchResponse","description":"Search response for news assets.","examples":[{"query":"tesla","count":1,"period_days":7,"results":[{"ticker":"TSLA","name":"Tesla Inc.","type":"Stock","exchange":"NASDAQ","sector":"Consumer Discretionary","country":"United States","aliases":["TSLA","NASDAQ:TSLA","Tesla"],"summary":{"mentions":342,"buzz_score":87.5,"trend":"rising","sentiment_score":0.23,"bearish_pct":18,"bullish_pct":45,"source_count":8}}]}]},"NewsSearchResultItem":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol","examples":["TSLA"]},"name":{"type":"string","title":"Name","description":"Company name","examples":["Tesla Inc."]},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type","description":"Asset type (Stock, ETF, etc.)","examples":["Stock"]},"exchange":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Exchange","description":"Stock exchange (NYSE, NASDAQ, etc.)","examples":["NASDAQ"]},"sector":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sector","description":"Industry sector","examples":["Consumer Discretionary"]},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"Country of headquarters","examples":["United States"]},"aliases":{"items":{"type":"string"},"type":"array","title":"Aliases","description":"Configured News graph matching terms, including terms with no mentions in the summary window; article acceptance also depends on worker safety and context checks","examples":[["TSLA","NASDAQ:TSLA","Tesla"]]},"summary":{"$ref":"#/components/schemas/NewsSearchSummary","description":"Last-7-days news summary for this asset"}},"type":"object","required":["ticker","name","summary"],"title":"NewsSearchResultItem","description":"Individual news search result item."},"NewsSearchSummary":{"properties":{"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"News mentions in the last 7 UTC calendar days","examples":[342]},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Buzz score over the last 7 UTC calendar days","examples":[87.5]},"trend":{"anyOf":[{"type":"string","enum":["rising","falling","stable"]},{"type":"null"}],"title":"Trend","description":"Activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions/articles and source breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["rising"]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average sentiment score over the last 7 UTC calendar days","examples":[0.23]}},"type":"object","required":["mentions","buzz_score"],"title":"NewsSearchSummary","description":"Compact last-7-days summary attached to news search results."},"NewsSourceCount":{"properties":{"source":{"type":"string","title":"Source","description":"News source identifier","examples":["reuters"]},"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"Mentions from this source","examples":[89]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average sentiment score for this source in the selected period","examples":[0.21]},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Contributor-level buzz score for this source in the selected period","examples":[58.4]},"count":{"type":"integer","minimum":0.0,"title":"Count","description":"Deprecated alias for mentions. Use mentions instead.","deprecated":true,"examples":[89]}},"type":"object","required":["source","mentions","count"],"title":"NewsSourceCount","description":"News source contributor metrics for a stock detail response."},"NewsStatsResponse":{"properties":{"total_mentions":{"type":"integer","title":"Total Mentions","description":"All-time number of stored news stock mentions","examples":[12833]},"unique_tickers":{"type":"integer","title":"Unique Tickers","description":"Number of unique tickers with news mentions","examples":[65]},"mentions_today":{"type":"integer","title":"Mentions Today","description":"News mention rows created since today's UTC midnight","default":0,"examples":[342]},"unique_tickers_today":{"type":"integer","title":"Unique Tickers Today","description":"Unique tickers with news mention rows since today's UTC midnight","default":0,"examples":[21]},"supported_tickers":{"type":"integer","title":"Supported Tickers","description":"Number of supported public tickers in the News reference catalog","examples":[35000]}},"type":"object","required":["total_mentions","unique_tickers","supported_tickers"],"title":"NewsStatsResponse","description":"News service statistics.","examples":[{"total_mentions":12833,"unique_tickers":65,"mentions_today":342,"unique_tickers_today":21,"supported_tickers":35000}]},"NewsStockSentiment":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol","examples":["TSLA"]},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name","description":"Company or fund name from resolved instrument metadata or the Legacy reference (null if unavailable)","examples":["Tesla, Inc."]},"found":{"type":"boolean","title":"Found","description":"Legacy v1 data-availability flag. `true` means this service has qualifying data for this asset/window. `false` means the asset is supported, but this service has no qualifying data for the requested window. Planned for removal in v2.","deprecated":true},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Buzz Score (0-100). Asymptotic scaling above 50.","examples":[87.5]},"mentions":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Mentions","description":"Total mentions in the selected period","examples":[342]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average sentiment score (-1 bearish to +1 bullish)","examples":[0.23]},"positive_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Positive Count","description":"Deprecated. Prefer bullish_pct with mentions for public analysis; retained for v1 compatibility.","deprecated":true,"examples":[154]},"negative_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Negative Count","description":"Deprecated. Prefer bearish_pct with mentions for public analysis; retained for v1 compatibility.","deprecated":true,"examples":[62]},"neutral_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Neutral Count","description":"Deprecated. Prefer bullish_pct, bearish_pct and mentions for public analysis; retained for v1 compatibility.","deprecated":true,"examples":[126]},"source_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Source Count","description":"Number of sources with mentions","examples":[8]},"trend":{"anyOf":[{"type":"string","enum":["rising","falling","stable"]},{"type":"null"}],"title":"Trend","description":"Activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions/articles and source breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["rising"]},"bullish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bullish Pct","description":"Percentage of bullish mentions","examples":[45]},"bearish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bearish Pct","description":"Percentage of bearish mentions","examples":[18]},"period_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Period Days","description":"Analysis period in days","examples":[7]},"top_sources":{"anyOf":[{"items":{"$ref":"#/components/schemas/NewsSourceCount"},"type":"array"},{"type":"null"}],"title":"Top Sources","description":"Top sources by mention count"},"daily_trend":{"anyOf":[{"items":{"$ref":"#/components/schemas/DailyTrendItem"},"type":"array"},{"type":"null"}],"title":"Daily Trend","description":"Daily mention breakdown for the selected period, with sentiment and buzz_score"},"top_mentions":{"anyOf":[{"items":{"$ref":"#/components/schemas/NewsTopMention"},"type":"array"},{"type":"null"}],"title":"Top Mentions","description":"Top news mentions from the selected period, ranked by recency"}},"type":"object","required":["ticker","found"],"title":"NewsStockSentiment","description":"Detailed sentiment analysis for a specific stock ticker from news mentions.","examples":[{"ticker":"TSLA","company_name":"Tesla, Inc.","found":true,"buzz_score":87.5,"mentions":342,"sentiment_score":0.23,"source_count":8,"trend":"rising","bullish_pct":45,"bearish_pct":18,"period_days":7,"top_sources":[{"source":"reuters","mentions":89,"count":89},{"source":"benzinga","mentions":67,"count":67}],"daily_trend":[{"date":"2026-03-05","mentions":52,"sentiment_score":0.31,"buzz_score":42.8,"bullish_pct":58,"bearish_pct":19},{"date":"2026-03-04","mentions":48,"sentiment_score":0.18,"buzz_score":38.5,"bullish_pct":46,"bearish_pct":21}],"top_mentions":[{"text_snippet":"TSLA looking strong after production update...","sentiment_score":0.85,"sentiment_label":"positive","source":"reuters","created_utc":"2026-03-05T10:30:00+00:00"}]}]},"NewsTopMention":{"properties":{"text_snippet":{"type":"string","title":"Text Snippet","description":"Excerpt from the mention","examples":["NVIDIA earnings beat expectations..."]},"sentiment_score":{"type":"number","maximum":1.0,"minimum":-1.0,"title":"Sentiment Score","description":"Sentiment score (-1 to +1)","examples":[0.73]},"sentiment_label":{"type":"string","title":"Sentiment Label","description":"Sentiment label (positive/negative/neutral)","examples":["positive"]},"source":{"type":"string","title":"Source","description":"Source publication identifier","examples":["reuters"]},"created_utc":{"type":"string","title":"Created Utc","description":"ISO timestamp of creation","examples":["2026-03-05T12:30:00+00:00"]}},"type":"object","required":["text_snippet","sentiment_score","sentiment_label","source","created_utc"],"title":"NewsTopMention","description":"Top mention item from news."},"NewsTrendingCountry":{"properties":{"buzz_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Buzz Score","description":"Aggregated Buzz Score (0-100)","examples":[78.4]},"trend":{"type":"string","enum":["rising","falling","stable"],"title":"Trend","description":"Activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions/articles and source breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["rising"]},"mentions":{"type":"integer","title":"Mentions","description":"Total mentions","examples":[4523]},"unique_tickers":{"type":"integer","title":"Unique Tickers","description":"Number of unique tickers mentioned","examples":[34]},"source_count":{"type":"integer","title":"Source Count","description":"Number of distinct news sources with mentions","examples":[15]},"sentiment_score":{"type":"number","maximum":1.0,"minimum":-1.0,"title":"Sentiment Score","description":"Weighted average sentiment (-1 bearish to +1 bullish)","examples":[0.28]},"bullish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bullish Pct","description":"Percentage of bullish mentions","examples":[54]},"bearish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bearish Pct","description":"Percentage of bearish mentions","examples":[22]},"trend_history":{"items":{"type":"number"},"type":"array","title":"Trend History","description":"Daily dimension buzz scores (oldest to newest). Length follows the resolved period, with a minimum of 7 values. Every slot describes only its UTC calendar day. The live final value describes today so far and can differ from period buzz_score. Closed historical windows end at `to`.","examples":[[45.2,48.1,52.3,55.0,58.2,61.5,78.4]]},"top_tickers":{"items":{"type":"string"},"type":"array","maxItems":5,"title":"Top Tickers","description":"Top 5 tickers by mentions","examples":[["NVDA","AAPL","MSFT","AMD","GOOGL"]]},"country":{"type":"string","title":"Country","description":"Country name","examples":["United States"]}},"type":"object","required":["buzz_score","trend","mentions","unique_tickers","source_count","sentiment_score","bullish_pct","bearish_pct","trend_history","top_tickers","country"],"title":"NewsTrendingCountry","description":"Trending country with aggregated buzz metrics from news.","examples":[{"buzz_score":82.3,"trend":"stable","mentions":8934,"unique_tickers":156,"source_count":18,"sentiment_score":0.21,"bullish_pct":48,"bearish_pct":26,"trend_history":[52.1,54.0,56.8,59.2,61.0,60.1,82.3],"top_tickers":["NVDA","TSLA","AAPL","AMD","PLTR"],"country":"United States"}]},"NewsTrendingSector":{"properties":{"buzz_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Buzz Score","description":"Aggregated Buzz Score (0-100)","examples":[78.4]},"trend":{"type":"string","enum":["rising","falling","stable"],"title":"Trend","description":"Activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions/articles and source breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["rising"]},"mentions":{"type":"integer","title":"Mentions","description":"Total mentions","examples":[4523]},"unique_tickers":{"type":"integer","title":"Unique Tickers","description":"Number of unique tickers mentioned","examples":[34]},"source_count":{"type":"integer","title":"Source Count","description":"Number of distinct news sources with mentions","examples":[15]},"sentiment_score":{"type":"number","maximum":1.0,"minimum":-1.0,"title":"Sentiment Score","description":"Weighted average sentiment (-1 bearish to +1 bullish)","examples":[0.28]},"bullish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bullish Pct","description":"Percentage of bullish mentions","examples":[54]},"bearish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bearish Pct","description":"Percentage of bearish mentions","examples":[22]},"trend_history":{"items":{"type":"number"},"type":"array","title":"Trend History","description":"Daily dimension buzz scores (oldest to newest). Length follows the resolved period, with a minimum of 7 values. Every slot describes only its UTC calendar day. The live final value describes today so far and can differ from period buzz_score. Closed historical windows end at `to`.","examples":[[45.2,48.1,52.3,55.0,58.2,61.5,78.4]]},"top_tickers":{"items":{"type":"string"},"type":"array","maxItems":5,"title":"Top Tickers","description":"Top 5 tickers by mentions","examples":[["NVDA","AAPL","MSFT","AMD","GOOGL"]]},"sector":{"type":"string","title":"Sector","description":"Industry sector name","examples":["Technology"]}},"type":"object","required":["buzz_score","trend","mentions","unique_tickers","source_count","sentiment_score","bullish_pct","bearish_pct","trend_history","top_tickers","sector"],"title":"NewsTrendingSector","description":"Trending sector with aggregated buzz metrics from news.","examples":[{"buzz_score":78.4,"trend":"rising","mentions":4523,"unique_tickers":34,"source_count":15,"sentiment_score":0.28,"bullish_pct":54,"bearish_pct":22,"trend_history":[45.2,48.1,52.3,55.0,58.2,61.5,78.4],"top_tickers":["NVDA","AAPL","MSFT","AMD","GOOGL"],"sector":"Technology"}]},"NewsTrendingStock":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol","examples":["TSLA"]},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name","description":"Company or fund name from resolved instrument metadata or the Legacy reference (null if unavailable)","examples":["Tesla, Inc."]},"buzz_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Buzz Score","description":"Buzz Score (0-100). Asymptotic scaling above 50.","examples":[87.5]},"trend":{"type":"string","enum":["rising","falling","stable"],"title":"Trend","description":"Activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions/articles and source breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["rising"]},"mentions":{"type":"integer","title":"Mentions","description":"Total number of mentions","examples":[342]},"source_count":{"type":"integer","title":"Source Count","description":"Number of distinct news sources with mentions","examples":[8]},"sentiment_score":{"type":"number","maximum":1.0,"minimum":-1.0,"title":"Sentiment Score","description":"Average sentiment score (-1 bearish to +1 bullish)","examples":[0.23]},"bullish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bullish Pct","description":"Percentage of bullish mentions","examples":[45]},"bearish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bearish Pct","description":"Percentage of bearish mentions","examples":[18]},"trend_history":{"items":{"type":"number"},"type":"array","title":"Trend History","description":"Daily buzz scores (oldest→newest). Length follows the resolved period, with a minimum of 7 values. Values 0-100.","examples":[[12.3,15.2,18.7,22.1,28.5,35.2,42.8]]}},"type":"object","required":["ticker","buzz_score","trend","mentions","source_count","sentiment_score","bullish_pct","bearish_pct"],"title":"NewsTrendingStock","description":"Trending stock with buzz metrics from news sources.","examples":[{"ticker":"TSLA","company_name":"Tesla, Inc.","buzz_score":87.5,"trend":"rising","mentions":342,"source_count":8,"sentiment_score":0.23,"bullish_pct":45,"bearish_pct":18,"trend_history":[45.2,52.1,48.7,67.3,72.1,78.4,87.5]}]},"PolymarketCompareResponse":{"properties":{"period_days":{"type":"integer","maximum":365.0,"minimum":1.0,"title":"Period Days","description":"Analysis period in days"},"stocks":{"items":{"$ref":"#/components/schemas/PolymarketCompareStockItem"},"type":"array","title":"Stocks","description":"Stocks sorted by buzz_score descending"}},"type":"object","required":["period_days","stocks"],"title":"PolymarketCompareResponse","description":"Response for compare endpoint.","examples":[{"period_days":7,"stocks":[{"ticker":"AAPL","company_name":"Apple Inc.","buzz_score":68.9,"trend":"stable","trade_count":312,"market_count":27,"current_market_count":12,"unique_traders":119,"sentiment_score":0.28,"bullish_pct":64,"bearish_pct":36,"total_liquidity":128000.0,"trend_history":[48.2,51.0,55.3,61.1,65.8,69.2,68.9]}]}]},"PolymarketCompareStockItem":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol"},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name","description":"Company name"},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Buzz score (0-100)"},"trend":{"anyOf":[{"type":"string","enum":["rising","falling","stable"]},{"type":"null"}],"title":"Trend","description":"Flow momentum over the current 3 UTC days vs previous 3 UTC days using trades, volume, market breadth and liquidity; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today). Null when no qualifying activity exists."},"trade_count":{"type":"integer","minimum":0.0,"title":"Trade Count","description":"Trade count in selected period"},"market_count":{"type":"integer","minimum":0.0,"title":"Market Count","description":"Distinct markets that existed for ticker within the selected UTC window, counted by market-catalog lifetime overlap"},"current_market_count":{"type":"integer","minimum":0.0,"title":"Current Market Count","description":"Number of currently open markets in the latest UTC-day snapshot for ticker; use this for live-only market breadth"},"unique_traders":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Unique Traders","description":"Exact distinct union of observed proxy and explicit maker wallet hashes for the delivered scope and UTC window; null when retained wallet-level trades do not fully cover the window; not a complete market-wide participant census"},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Orderbook-aware implied sentiment; null when no directional sentiment evidence exists in the selected period"},"bullish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bullish Pct","description":"Outcome-aware bullish market percentage"},"bearish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bearish Pct","description":"Outcome-aware bearish market percentage"},"total_liquidity":{"type":"number","minimum":0.0,"title":"Total Liquidity","description":"Windowed aggregated liquidity signal in USD over the selected period; not a current snapshot"},"trend_history":{"items":{"type":"number"},"type":"array","title":"Trend History","description":"Recent buzz history (oldest→newest). Length follows the resolved period, with a minimum of 7 values when data exists. Closed historical windows end at `to`. Empty when no qualifying data exists."}},"type":"object","required":["ticker","buzz_score","trade_count","market_count","current_market_count","total_liquidity"],"title":"PolymarketCompareStockItem","description":"Single stock item for Polymarket compare endpoint."},"PolymarketDailyTrendItem":{"properties":{"date":{"type":"string","title":"Date","description":"Date in YYYY-MM-DD format","examples":["2026-02-13"]},"trade_count":{"type":"integer","title":"Trade Count","description":"Trade count on this date","examples":[5]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Outcome-aware implied sentiment on this date; can come from orderbook evidence or legacy traded price evidence, null when no sentiment evidence exists","examples":[0.25]},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Buzz score on this date; null when neither a daily aggregate nor a live fallback could be computed for this date","examples":[64.1]},"bullish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bullish Pct","description":"Outcome-aware bullish market-direction percentage for this date","examples":[64]},"bearish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bearish Pct","description":"Outcome-aware bearish market-direction percentage for this date","examples":[21]}},"type":"object","required":["date","trade_count"],"title":"PolymarketDailyTrendItem","description":"Daily trend item for stock detail endpoint."},"PolymarketHealthResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Current health status","examples":["healthy"]},"service":{"type":"string","title":"Service","description":"Service identifier","examples":["polymarket-stocks"]},"version":{"type":"string","title":"Version","description":"API version","examples":["1.53.4"]},"total_mentions":{"type":"integer","minimum":0.0,"title":"Total Mentions","description":"Mentions observed in the most recent scrape cycle; returns 0 when scrape telemetry is unavailable."},"tickers_tracked":{"type":"integer","minimum":0.0,"title":"Tickers Tracked","description":"Distinct tickers observed in the most recent scrape cycle; returns 0 when scrape telemetry is unavailable."},"scheduler":{"anyOf":[{"$ref":"#/components/schemas/PolymarketSchedulerStatus"},{"type":"null"}],"description":"Polymarket worker status"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message when unhealthy"}},"type":"object","required":["status","service","version","total_mentions","tickers_tracked"],"title":"PolymarketHealthResponse","description":"Polymarket health response.","examples":[{"status":"healthy","service":"polymarket-stocks","version":"1.53.4","total_mentions":8421,"tickers_tracked":119,"scheduler":{"running":true,"last_scrape":"2026-02-18T10:00:00Z","scrape_count":58,"error_count":1,"success_rate":0.983}}]},"PolymarketMarketSentimentDriver":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol","examples":["AAPL"]},"trade_count":{"type":"integer","minimum":0.0,"title":"Trade Count","description":"Trade count for this asset in the selected period","examples":[52]},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Asset buzz score in the selected period","examples":[68.9]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Implied sentiment score for this asset in the selected period","examples":[0.28]}},"type":"object","required":["ticker","trade_count","buzz_score"],"title":"PolymarketMarketSentimentDriver","description":"Top asset contributing to the service-level Polymarket market sentiment."},"PolymarketMarketSentimentResponse":{"properties":{"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Service-wide Polymarket heat score relative to the service's trailing 90-day baseline. Around 50 = normal activity, higher values = hotter-than-usual Polymarket activity.","examples":[58.4]},"trend":{"anyOf":[{"type":"string","enum":["rising","falling","stable"]},{"type":"null"}],"title":"Trend","description":"Flow momentum over the current 3 UTC days vs previous 3 UTC days using trades, volume, market breadth and liquidity; not price movement. Null when the selected window has no measurable Polymarket heat. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["rising"]},"trade_count":{"type":"integer","minimum":0.0,"title":"Trade Count","description":"Service-wide trade count in the selected period","examples":[512]},"market_count":{"type":"integer","minimum":0.0,"title":"Market Count","description":"Sum of ticker-level catalog lifetime-overlap market counts in the selected UTC window; not a cross-ticker global condition-id union","examples":[93]},"current_market_count":{"type":"integer","minimum":0.0,"title":"Current Market Count","description":"Sum of ticker-level currently open markets in the latest UTC-day snapshot; use this for live-only market breadth","examples":[64]},"unique_traders":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Unique Traders","description":"Exact service-wide observed participant/proxy-wallet union in the selected period; null when retained wallet-level trades do not fully cover the requested window","examples":[281]},"total_liquidity":{"type":"number","minimum":0.0,"title":"Total Liquidity","description":"Windowed aggregated liquidity signal in USD over the selected period","examples":[245000.0]},"active_tickers":{"type":"integer","minimum":0.0,"title":"Active Tickers","description":"Number of tickers with market activity in the selected period","examples":[31]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Service-wide weighted orderbook-aware implied sentiment score","examples":[0.11]},"positive_count":{"type":"integer","minimum":0.0,"title":"Positive Count","description":"Deprecated. Outcome-aware bullish market count retained for v1 compatibility; prefer bullish_pct with trade_count and market_count for public analysis.","deprecated":true,"examples":[41]},"negative_count":{"type":"integer","minimum":0.0,"title":"Negative Count","description":"Deprecated. Outcome-aware bearish market count retained for v1 compatibility; prefer bearish_pct with trade_count and market_count for public analysis.","deprecated":true,"examples":[29]},"neutral_count":{"type":"integer","minimum":0.0,"title":"Neutral Count","description":"Deprecated. Outcome-aware neutral/unclassified market count retained for v1 compatibility; prefer bullish_pct, bearish_pct, trade_count and market_count for public analysis.","deprecated":true,"examples":[23]},"bullish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bullish Pct","description":"Outcome-aware bullish market percentage","examples":[44]},"bearish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bearish Pct","description":"Outcome-aware bearish market percentage","examples":[31]},"trend_history":{"items":{"type":"number"},"type":"array","title":"Trend History","description":"Daily service-wide buzz scores (oldest→newest) using the same relative baseline calibration. Length = max(requested_days, 7) for successful requests; windows before platform availability return HTTP 422.","examples":[[52.1,54.0,56.8,59.2,61.0,60.1,58.4]]},"drivers":{"items":{"$ref":"#/components/schemas/PolymarketMarketSentimentDriver"},"type":"array","title":"Drivers","description":"Top 5 stocks of the selected period by buzz_score. trade_count and sentiment_score cover every day of the period."}},"type":"object","required":["buzz_score","trade_count","market_count","current_market_count","total_liquidity","active_tickers","positive_count","negative_count","neutral_count","bullish_pct","bearish_pct"],"title":"PolymarketMarketSentimentResponse","description":"Service-level Polymarket market sentiment across all tracked stocks.","examples":[{"buzz_score":58.4,"trend":"stable","trade_count":512,"market_count":93,"current_market_count":64,"unique_traders":281,"total_liquidity":245000.0,"active_tickers":31,"sentiment_score":0.11,"positive_count":41,"negative_count":29,"neutral_count":23,"bullish_pct":44,"bearish_pct":31,"trend_history":[52.1,54.0,56.8,59.2,61.0,60.1,58.4],"drivers":[{"ticker":"AAPL","trade_count":52,"buzz_score":68.9,"sentiment_score":0.28},{"ticker":"TSLA","trade_count":47,"buzz_score":66.3,"sentiment_score":0.19}]}]},"PolymarketPulseEvidence":{"properties":{"directional_coverage":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Directional Coverage","description":"Share of current open snapshot markets with outcome-aware directional evidence"},"traded_market_pct":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Traded Market Pct","description":"Share of current open snapshot markets with trades in the latest UTC day"},"zero_trade_market_pct":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Zero Trade Market Pct","description":"Share of current open snapshot markets without trades in the latest UTC day"},"avg_spread":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Avg Spread","description":"Average YES-token spread across current open snapshot markets with bid/ask spread evidence"},"snapshot_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Snapshot At","description":"Latest stored snapshot timestamp used by the pulse read model"}},"type":"object","title":"PolymarketPulseEvidence","description":"Compact data-quality evidence for the ticker-level Polymarket pulse."},"PolymarketRawMentionItem":{"properties":{"condition_id":{"type":"string","title":"Condition Id","description":"Polymarket condition ID","examples":["0xabc..."]},"event_id":{"type":"string","title":"Event Id","description":"Polymarket event ID","examples":["12345"]},"market_slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Market Slug","description":"Polymarket market slug","examples":["nvda-up-or-down-on-april-20-2026"]},"question":{"type":"string","title":"Question","description":"Market question/title","examples":["NVDA up or down on April 20?"]},"market_type":{"type":"string","title":"Market Type","description":"Derived market type (`up_down`, `close_above`, `hit_target`, `earnings` or `other`)","examples":["up_down"]},"strike_price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Strike Price","description":"Extracted strike price when available","examples":[250.0]},"yes_price":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Yes Price","description":"YES price from this snapshot","examples":[0.63]},"no_price":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"No Price","description":"NO price from this snapshot","examples":[0.37]},"reference_price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Reference Price","description":"Stock reference price attached during scrape when needed for range-ladder classification","examples":[101.68]},"reference_price_timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reference Price Timestamp","description":"Timestamp for `reference_price` when available","examples":["2026-04-20T14:30:00Z"]},"liquidity":{"type":"number","minimum":0.0,"title":"Liquidity","description":"Market liquidity in USD at snapshot time","examples":[7905.52]},"volume_24h":{"type":"number","minimum":0.0,"title":"Volume 24H","description":"Rolling 24h market volume in USD at snapshot time","examples":[2408.43]},"trade_count":{"type":"integer","minimum":0.0,"title":"Trade Count","description":"UTC-day trade count observed for this market snapshot","examples":[42]},"buy_trades":{"type":"integer","minimum":0.0,"title":"Buy Trades","description":"UTC-day Polymarket BUY trades for this snapshot; activity counter, not bullishness","examples":[23]},"sell_trades":{"type":"integer","minimum":0.0,"title":"Sell Trades","description":"UTC-day Polymarket SELL trades for this snapshot; activity counter, not bearishness","examples":[19]},"unique_traders":{"type":"integer","minimum":0.0,"title":"Unique Traders","description":"UTC-day observed participant/proxy-wallet counter for this market snapshot","examples":[31]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Outcome-aware market price sentiment for this snapshot; prefers orderbook midpoint when available, falls back to YES/NO price and is null when direction or evidence is unavailable","examples":[0.26]},"sentiment_label":{"anyOf":[{"type":"string","enum":["positive","negative","neutral"]},{"type":"null"}],"title":"Sentiment Label","description":"Classification derived from `sentiment_score`: positive=bullish, negative=bearish, neutral=flat; null when `sentiment_score` is null","examples":["positive"]},"end_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"End Date","description":"Market end timestamp when available. Unlike summary `top_mentions`, raw rows preserve the full timestamp from the stored snapshot.","examples":["2026-04-20T23:59:00Z"]},"active":{"type":"boolean","title":"Active","description":"Whether the market is currently open; false for closed or ended markets","examples":[true]},"market_status":{"type":"string","enum":["tradable","open","resolved","inactive","expired"],"title":"Market Status","description":"Compact current market status derived from active, closed, accepting_orders and end_date","examples":["tradable"]},"fetched_at":{"type":"string","format":"date-time","title":"Fetched At","description":"Snapshot fetch timestamp","examples":["2026-04-20T15:00:00Z"]}},"type":"object","required":["condition_id","event_id","question","market_type","liquidity","volume_24h","trade_count","buy_trades","sell_trades","unique_traders","active","market_status","fetched_at"],"title":"PolymarketRawMentionItem","description":"Raw Polymarket market snapshot row for one stock ticker."},"PolymarketRawMentionsResponse":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol","examples":["NVDA"]},"period_days":{"type":"integer","minimum":1.0,"title":"Period Days","description":"Lookback window used for the query","examples":[7]},"count":{"type":"integer","minimum":0.0,"title":"Count","description":"Total number of matching raw rows before limit and offset are applied; only the requested page is returned","examples":[1]},"results":{"items":{"$ref":"#/components/schemas/PolymarketRawMentionItem"},"type":"array","title":"Results","description":"Raw market snapshot rows ordered by newest first"}},"type":"object","required":["ticker","period_days","count","results"],"title":"PolymarketRawMentionsResponse","description":"Paginated raw Polymarket snapshot rows for a single stock ticker.","examples":[{"ticker":"NVDA","period_days":7,"count":1,"results":[{"condition_id":"0xabc...","event_id":"12345","market_slug":"nvda-up-or-down-on-april-20-2026","question":"NVDA up or down on April 20?","market_type":"up_down","strike_price":250.0,"yes_price":0.63,"no_price":0.37,"reference_price":247.82,"reference_price_timestamp":"2026-04-20T14:30:00Z","liquidity":7905.52,"volume_24h":2408.43,"trade_count":42,"buy_trades":23,"sell_trades":19,"unique_traders":31,"sentiment_score":0.26,"sentiment_label":"positive","end_date":"2026-04-20T23:59:00Z","active":true,"market_status":"tradable","fetched_at":"2026-04-20T15:00:00Z"}]}]},"PolymarketSchedulerStatus":{"properties":{"running":{"type":"boolean","title":"Running","description":"Whether data collection is running"},"last_scrape":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Scrape","description":"ISO timestamp of last scrape"},"scrape_count":{"type":"integer","title":"Scrape Count","description":"Total scrape cycles","default":0},"error_count":{"type":"integer","title":"Error Count","description":"Total failed cycles","default":0},"success_rate":{"type":"number","title":"Success Rate","description":"Success ratio","default":0.0},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note","description":"Additional worker status note"}},"type":"object","required":["running"],"title":"PolymarketSchedulerStatus","description":"Polymarket data collection status.","examples":[{"running":true,"last_scrape":"2026-02-18T10:00:00Z","scrape_count":58,"error_count":1,"success_rate":0.983}]},"PolymarketSearchResponse":{"properties":{"query":{"type":"string","title":"Query","description":"Original search query","examples":["tesla"]},"count":{"type":"integer","title":"Count","description":"Total number of matching results before the limit is applied","examples":[1]},"period_days":{"type":"integer","minimum":1.0,"title":"Period Days","description":"Fixed lookback window used for each summary block","examples":[7]},"results":{"items":{"$ref":"#/components/schemas/PolymarketSearchResultItem"},"type":"array","title":"Results","description":"Top matching stocks capped by the requested limit"}},"type":"object","required":["query","count","period_days","results"],"title":"PolymarketSearchResponse","description":"Search results for Polymarket stocks.","examples":[{"query":"tesla","count":1,"period_days":7,"results":[{"ticker":"TSLA","name":"Tesla Inc.","type":"Stock","exchange":"NASDAQ","sector":"Consumer Discretionary","country":"United States","aliases":["Tesla","Elon"],"summary":{"trade_count":14,"buzz_score":71.4,"trend":"rising","sentiment_score":0.34,"bearish_pct":33,"bullish_pct":67,"current_market_count":12,"market_count":27,"total_liquidity":94750.0,"unique_traders":119}}]}]},"PolymarketSearchResultItem":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol","examples":["TSLA"]},"name":{"type":"string","title":"Name","description":"Company name","examples":["Tesla Inc."]},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type","description":"Asset type (Stock, ETF, etc.)","examples":["Stock"]},"exchange":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Exchange","description":"Stock exchange","examples":["NASDAQ"]},"sector":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sector","description":"Industry sector","examples":["Consumer Discretionary"]},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"Country of headquarters","examples":["United States"]},"aliases":{"items":{"type":"string"},"type":"array","title":"Aliases","description":"Alternative names/aliases","examples":[["Tesla","Elon"]]},"summary":{"$ref":"#/components/schemas/PolymarketSearchSummary","description":"Last-7-days Polymarket summary for this asset"}},"type":"object","required":["ticker","name","summary"],"title":"PolymarketSearchResultItem","description":"Individual Polymarket search result item."},"PolymarketSearchSummary":{"properties":{"trade_count":{"type":"integer","minimum":0.0,"title":"Trade Count","description":"Trade count in the last 7 UTC calendar days","examples":[14]},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Buzz score over the last 7 UTC calendar days","examples":[71.4]},"trend":{"anyOf":[{"type":"string","enum":["rising","falling","stable"]},{"type":"null"}],"title":"Trend","description":"Flow momentum over the current 3 UTC days vs previous 3 UTC days using trades, volume, market breadth and liquidity; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["rising"]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Orderbook-aware implied sentiment over the last 7 UTC calendar days","examples":[0.34]}},"type":"object","required":["trade_count","buzz_score"],"title":"PolymarketSearchSummary","description":"Compact last-7-days summary attached to Polymarket search results."},"PolymarketStatsResponse":{"properties":{"total_trades":{"type":"integer","minimum":0.0,"title":"Total Trades","description":"Total Polymarket trade activity from daily aggregates"},"total_markets":{"type":"integer","minimum":0.0,"title":"Total Markets","description":"Distinct Polymarket condition_id count"},"unique_tickers":{"type":"integer","minimum":0.0,"title":"Unique Tickers","description":"Distinct tickers with Polymarket market rows in the database"},"open_markets_current":{"type":"integer","minimum":0.0,"title":"Open Markets Current","description":"Currently open Polymarket markets where active=true, closed=false and end_date has not passed","default":0},"open_tickers_current":{"type":"integer","minimum":0.0,"title":"Open Tickers Current","description":"Distinct tickers with at least one currently open Polymarket market","default":0},"traded_markets_today":{"type":"integer","minimum":0.0,"title":"Traded Markets Today","description":"Distinct Polymarket condition_id values with UTC-day trade activity","default":0},"traded_tickers_today":{"type":"integer","minimum":0.0,"title":"Traded Tickers Today","description":"Distinct tickers with UTC-day Polymarket trade activity","default":0},"trades_today":{"type":"integer","minimum":0.0,"title":"Trades Today","description":"Polymarket trade activity during today's UTC date","default":0},"supported_tickers":{"type":"integer","minimum":0.0,"title":"Supported Tickers","description":"Number of supported stock tickers"}},"type":"object","required":["total_trades","total_markets","unique_tickers","supported_tickers"],"title":"PolymarketStatsResponse","description":"Polymarket service statistics.","examples":[{"total_trades":15420,"total_markets":713,"unique_tickers":119,"open_markets_current":284,"open_tickers_current":71,"traded_markets_today":39,"traded_tickers_today":17,"trades_today":84,"supported_tickers":35000}]},"PolymarketStockDetailResponse":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol","examples":["AAPL"]},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name","description":"Company name","examples":["Apple Inc."]},"found":{"type":"boolean","title":"Found","description":"Legacy v1 data-availability flag. `true` means this service has qualifying data for this asset/window. `false` means the asset is supported, but this service has no qualifying data for the requested window. Planned for removal in v2.","deprecated":true},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Buzz score (0-100)","examples":[68.9]},"trend":{"anyOf":[{"type":"string","enum":["rising","falling","stable"]},{"type":"null"}],"title":"Trend","description":"Flow momentum over the current 3 UTC days vs previous 3 UTC days using trades, volume, market breadth and liquidity; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["stable"]},"period_days":{"anyOf":[{"type":"integer","maximum":365.0,"minimum":1.0},{"type":"null"}],"title":"Period Days","description":"Analysis period in days","examples":[7]},"trade_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Trade Count","description":"Trade count in period","examples":[312]},"market_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Market Count","description":"Distinct markets that existed for ticker within the selected UTC window, counted by market-catalog lifetime overlap","examples":[27]},"current_market_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Current Market Count","description":"Number of currently open markets in the latest UTC-day snapshot for ticker; use this for live-only market breadth","examples":[12]},"unique_traders":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Unique Traders","description":"Exact distinct union of observed proxy and explicit maker wallet hashes for the delivered scope and UTC window; null when retained wallet-level trades do not fully cover the window; not a complete market-wide participant census","examples":[119]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Orderbook-aware implied sentiment; null when no directional sentiment evidence exists in the selected period","examples":[0.28]},"positive_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Positive Count","description":"Deprecated. Outcome-aware bullish market count retained for v1 compatibility; prefer bullish_pct with trade_count and market_count for public analysis.","deprecated":true,"examples":[9]},"negative_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Negative Count","description":"Deprecated. Outcome-aware bearish market count retained for v1 compatibility; prefer bearish_pct with trade_count and market_count for public analysis.","deprecated":true,"examples":[5]},"neutral_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Neutral Count","description":"Deprecated. Outcome-aware neutral/unclassified market count retained for v1 compatibility; prefer bullish_pct, bearish_pct, trade_count and market_count for public analysis.","deprecated":true,"examples":[2]},"bullish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bullish Pct","description":"Outcome-aware bullish market percentage","examples":[64]},"bearish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bearish Pct","description":"Outcome-aware bearish market percentage","examples":[36]},"total_liquidity":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Total Liquidity","description":"Windowed aggregated liquidity signal in USD over the selected period; not a current snapshot","examples":[128000.0]},"daily_trend":{"anyOf":[{"items":{"$ref":"#/components/schemas/PolymarketDailyTrendItem"},"type":"array"},{"type":"null"}],"title":"Daily Trend","description":"Daily activity breakdown for the selected period"},"top_mentions":{"anyOf":[{"items":{"$ref":"#/components/schemas/PolymarketTopMention"},"type":"array"},{"type":"null"}],"title":"Top Mentions","description":"Top markets with an active/open snapshot during the retained snapshot portion of the selected UTC-day period for this ticker (including the current UTC day so far), capped at 10 and sorted as representative sentiment evidence: outcome-aware directional markets first, opposing signals kept visible when present, then trade count, with non-open markets de-prioritized and 24h volume and liquidity as tie-breakers. For windows longer than raw snapshot retention, ticker analytics still use daily aggregates, while this list is limited to retained market snapshots. Item prices and liquidity come from the selected in-period snapshot, not necessarily the current market state. `active` indicates whether the market is currently open, so historical in-period evidence can now have a non-open current state. `market_status` gives the compact current state."},"pulse":{"anyOf":[{"$ref":"#/components/schemas/PolymarketTickerPulse"},{"type":"null"}],"description":"Compact current Polymarket interpretation built from locally stored latest snapshot evidence. Does not duplicate top-level aggregate fields; concrete market evidence remains in `top_mentions`."}},"type":"object","required":["ticker","found"],"title":"PolymarketStockDetailResponse","description":"Detailed Polymarket data for a single stock.","examples":[{"ticker":"AAPL","company_name":"Apple Inc.","found":true,"buzz_score":68.9,"trend":"stable","period_days":7,"trade_count":312,"market_count":27,"current_market_count":12,"unique_traders":119,"sentiment_score":0.28,"bullish_pct":64,"bearish_pct":36,"total_liquidity":128000.0,"daily_trend":[{"date":"2026-02-13","trade_count":5,"sentiment_score":0.25,"buzz_score":64.1,"bullish_pct":64,"bearish_pct":21}],"top_mentions":[{"condition_id":"0xabc...","question":"Will AAPL close above $220 this week?","market_type":"close_above","trade_count":42,"sentiment_score":0.23,"buzz_score":77.2,"yes_price":0.62,"no_price":0.38,"liquidity":7905.52,"volume_24h":2408.43,"end_date":"2026-02-28","active":true,"market_status":"tradable"}],"pulse":{"mood":"mixed","confidence":60.0,"thin_data":false,"why":["opposing_market_signals","upside_targets_rejected","floor_support"],"warnings":["high_average_spread","low_trade_breadth"],"evidence":{"directional_coverage":1.0,"traded_market_pct":0.231,"zero_trade_market_pct":0.769,"avg_spread":0.099,"snapshot_at":"2026-06-24T06:25:53Z"}}}]},"PolymarketTickerPulse":{"properties":{"mood":{"type":"string","enum":["bullish","bearish","mixed","event_driven","illiquid","unclear"],"title":"Mood","description":"Current compact Polymarket interpretation for this ticker"},"confidence":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Confidence","description":"Interpretation confidence capped by coverage, trade breadth, spread, liquidity and recency"},"thin_data":{"type":"boolean","title":"Thin Data","description":"True when current evidence is insufficient for a strong directional interpretation"},"why":{"items":{"type":"string"},"type":"array","maxItems":4,"minItems":1,"title":"Why","description":"Stable machine-readable reason codes explaining the pulse interpretation"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"Stable machine-readable data quality, freshness and tradability warnings"},"evidence":{"$ref":"#/components/schemas/PolymarketPulseEvidence","description":"Compact non-duplicative quality summary for the pulse inputs"}},"type":"object","required":["mood","confidence","thin_data","why","evidence"],"title":"PolymarketTickerPulse","description":"Compact interpretation layer for current ticker-level Polymarket data."},"PolymarketTopMention":{"properties":{"condition_id":{"type":"string","title":"Condition Id","description":"Polymarket condition ID","examples":["0xabc..."]},"question":{"type":"string","title":"Question","description":"Market question/title"},"market_type":{"type":"string","title":"Market Type","description":"Derived market type","examples":["close_above"]},"trade_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Trade Count","description":"UTC-day trade count from the selected in-period snapshot","examples":[42]},"sentiment_score":{"type":"number","maximum":1.0,"minimum":-1.0,"title":"Sentiment Score","description":"Outcome-aware market price sentiment for the selected in-period snapshot; prefers orderbook midpoint when available, falls back to YES/NO price and returns neutral 0.0 when direction is unclassified","examples":[0.23]},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Market-level activity buzz score for this selected in-period snapshot","examples":[77.2]},"yes_price":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Yes Price","description":"YES price from the selected in-period snapshot; not necessarily live"},"no_price":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"No Price","description":"NO price from the selected in-period snapshot; not necessarily live"},"liquidity":{"type":"number","minimum":0.0,"title":"Liquidity","description":"Selected in-period snapshot liquidity in USD; not necessarily live","examples":[7905.52]},"volume_24h":{"type":"number","minimum":0.0,"title":"Volume 24H","description":"Selected in-period snapshot rolling 24h volume in USD; not necessarily live","examples":[2408.43]},"end_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"End Date","description":"Market end date (ISO)","examples":["2026-02-28"]},"active":{"type":"boolean","title":"Active","description":"Whether the representative market state is open; snapshot-backed rows use current state, historical daily examples use stored representative state"},"market_status":{"type":"string","enum":["tradable","open","resolved","inactive","expired"],"title":"Market Status","description":"Compact market status for this representative item; snapshot-backed rows use current state, historical daily examples use stored representative state","examples":["tradable"]}},"type":"object","required":["condition_id","question","market_type","sentiment_score","liquidity","volume_24h","active","market_status"],"title":"PolymarketTopMention","description":"Top Polymarket market for a ticker with current open/closed state."},"PolymarketTrendingCountry":{"properties":{"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Aggregated activity/flow buzz score using trades, volume, breadth, liquidity and participation"},"trend":{"type":"string","enum":["rising","falling","stable"],"title":"Trend","description":"Flow momentum over the current 3 UTC days vs previous 3 UTC days using trades, volume, market breadth and liquidity; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)."},"trade_count":{"type":"integer","minimum":0.0,"title":"Trade Count","description":"Total trade count in period"},"market_count":{"type":"integer","minimum":0.0,"title":"Market Count","description":"Sum of ticker-level catalog lifetime-overlap market counts in the selected UTC window for this dimension; not a cross-ticker condition-id union"},"current_market_count":{"type":"integer","minimum":0.0,"title":"Current Market Count","description":"Sum of ticker-level currently open markets in the latest UTC-day snapshot; use this for live-only market breadth"},"unique_tickers":{"type":"integer","minimum":0.0,"title":"Unique Tickers","description":"Unique tickers in dimension"},"unique_traders":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Unique Traders","description":"Exact distinct union of observed proxy and explicit maker wallet hashes for the dimension and UTC window; null when retained wallet-level trades do not fully cover the window"},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Weighted implied sentiment; null when no underlying trades exist in the selected period"},"bullish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bullish Pct","description":"Outcome-aware bullish market percentage"},"bearish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bearish Pct","description":"Outcome-aware bearish market percentage"},"total_liquidity":{"type":"number","minimum":0.0,"title":"Total Liquidity","description":"Windowed aggregated liquidity signal in USD over the selected period; not a current snapshot"},"trend_history":{"items":{"type":"number"},"type":"array","title":"Trend History","description":"Daily dimension buzz scores (oldest to newest). Length follows the resolved period, with a minimum of 7 values. Every slot describes only its UTC calendar day. The live final value describes today so far and can differ from period buzz_score. Closed historical windows end at `to`.","examples":[[48.2,51.0,55.3,61.1,65.8,69.2,72.8]]},"top_tickers":{"items":{"type":"string"},"type":"array","maxItems":5,"title":"Top Tickers","description":"Top 5 tickers by trade_count"},"country":{"type":"string","title":"Country","description":"Country name","examples":["United States"]}},"type":"object","required":["buzz_score","trend","trade_count","market_count","current_market_count","unique_tickers","bullish_pct","bearish_pct","total_liquidity","trend_history","top_tickers","country"],"title":"PolymarketTrendingCountry","description":"Trending country on Polymarket.","examples":[{"buzz_score":70.1,"trend":"stable","trade_count":712,"market_count":265,"current_market_count":129,"unique_tickers":10,"unique_traders":402,"sentiment_score":0.18,"bullish_pct":58,"bearish_pct":42,"total_liquidity":472000.0,"trend_history":[52.1,54.0,56.8,59.2,61.0,60.1,70.1],"top_tickers":["AAPL","TSLA","NVDA","AMZN","GOOGL"],"country":"United States"}]},"PolymarketTrendingSector":{"properties":{"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Aggregated activity/flow buzz score using trades, volume, breadth, liquidity and participation"},"trend":{"type":"string","enum":["rising","falling","stable"],"title":"Trend","description":"Flow momentum over the current 3 UTC days vs previous 3 UTC days using trades, volume, market breadth and liquidity; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today)."},"trade_count":{"type":"integer","minimum":0.0,"title":"Trade Count","description":"Total trade count in period"},"market_count":{"type":"integer","minimum":0.0,"title":"Market Count","description":"Sum of ticker-level catalog lifetime-overlap market counts in the selected UTC window for this dimension; not a cross-ticker condition-id union"},"current_market_count":{"type":"integer","minimum":0.0,"title":"Current Market Count","description":"Sum of ticker-level currently open markets in the latest UTC-day snapshot; use this for live-only market breadth"},"unique_tickers":{"type":"integer","minimum":0.0,"title":"Unique Tickers","description":"Unique tickers in dimension"},"unique_traders":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Unique Traders","description":"Exact distinct union of observed proxy and explicit maker wallet hashes for the dimension and UTC window; null when retained wallet-level trades do not fully cover the window"},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Weighted implied sentiment; null when no underlying trades exist in the selected period"},"bullish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bullish Pct","description":"Outcome-aware bullish market percentage"},"bearish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bearish Pct","description":"Outcome-aware bearish market percentage"},"total_liquidity":{"type":"number","minimum":0.0,"title":"Total Liquidity","description":"Windowed aggregated liquidity signal in USD over the selected period; not a current snapshot"},"trend_history":{"items":{"type":"number"},"type":"array","title":"Trend History","description":"Daily dimension buzz scores (oldest to newest). Length follows the resolved period, with a minimum of 7 values. Every slot describes only its UTC calendar day. The live final value describes today so far and can differ from period buzz_score. Closed historical windows end at `to`.","examples":[[48.2,51.0,55.3,61.1,65.8,69.2,72.8]]},"top_tickers":{"items":{"type":"string"},"type":"array","maxItems":5,"title":"Top Tickers","description":"Top 5 tickers by trade_count"},"sector":{"type":"string","title":"Sector","description":"Sector name","examples":["Technology"]}},"type":"object","required":["buzz_score","trend","trade_count","market_count","current_market_count","unique_tickers","bullish_pct","bearish_pct","total_liquidity","trend_history","top_tickers","sector"],"title":"PolymarketTrendingSector","description":"Trending sector on Polymarket.","examples":[{"buzz_score":72.8,"trend":"rising","trade_count":312,"market_count":147,"current_market_count":71,"unique_tickers":6,"unique_traders":211,"sentiment_score":0.22,"bullish_pct":61,"bearish_pct":39,"total_liquidity":325000.0,"trend_history":[48.2,51.0,55.3,61.1,65.8,69.2,72.8],"top_tickers":["AAPL","MSFT","NVDA","TSLA","AMD"],"sector":"Technology"}]},"PolymarketTrendingStock":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol","examples":["TSLA"]},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name","description":"Company name","examples":["Tesla, Inc."]},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Polymarket activity/flow discovery score (0-100); not directional sentiment","examples":[71.4]},"trend":{"type":"string","enum":["rising","falling","stable"],"title":"Trend","description":"Flow momentum over the current 3 UTC days vs previous 3 UTC days using trades, volume, market breadth and liquidity; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["rising"]},"trade_count":{"type":"integer","minimum":0.0,"title":"Trade Count","description":"Trade count in selected period","examples":[312]},"market_count":{"type":"integer","minimum":0.0,"title":"Market Count","description":"Distinct markets that existed for ticker within the selected UTC window, counted by market-catalog lifetime overlap","examples":[27]},"current_market_count":{"type":"integer","minimum":0.0,"title":"Current Market Count","description":"Number of currently open markets in the latest UTC-day snapshot for ticker; use this for live-only market breadth","examples":[12]},"unique_traders":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Unique Traders","description":"Exact distinct union of observed proxy and explicit maker wallet hashes for the delivered scope and UTC window; null when retained wallet-level trades do not fully cover the window; not a complete market-wide participant census","examples":[119]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Orderbook-aware implied sentiment (-1 to +1); null when no directional sentiment evidence exists in the selected period","examples":[0.34]},"bullish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bullish Pct","description":"Outcome-aware bullish market percentage","examples":[67]},"bearish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bearish Pct","description":"Outcome-aware bearish market percentage","examples":[33]},"total_liquidity":{"type":"number","minimum":0.0,"title":"Total Liquidity","description":"Windowed aggregated liquidity signal in USD over the selected period; not a current snapshot","examples":[94750.0]},"trend_history":{"items":{"type":"number"},"type":"array","title":"Trend History","description":"Recent buzz history (oldest→newest). Length follows the resolved period, with a minimum of 7 values. Closed historical windows end at `to`.","examples":[[48.2,51.0,55.3,61.1,65.8,69.2,71.4]]}},"type":"object","required":["ticker","buzz_score","trend","trade_count","market_count","current_market_count","bullish_pct","bearish_pct","total_liquidity"],"title":"PolymarketTrendingStock","description":"Trending stock from Polymarket in Reddit/X-compatible shape.","examples":[{"ticker":"TSLA","company_name":"Tesla, Inc.","buzz_score":71.4,"trend":"rising","trade_count":312,"market_count":27,"current_market_count":12,"unique_traders":119,"sentiment_score":0.34,"bullish_pct":67,"bearish_pct":33,"total_liquidity":94750.0,"trend_history":[48.2,51.0,55.3,61.1,65.8,69.2,71.4]}]},"RateLimitError":{"properties":{"detail":{"$ref":"#/components/schemas/RateLimitErrorDetail","description":"Structured rate-limit details"}},"type":"object","required":["detail"],"title":"RateLimitError","description":"Error response for rate-limit exceeded responses."},"RateLimitErrorDetail":{"properties":{"error":{"type":"string","title":"Error","description":"Error type identifier"},"message":{"type":"string","title":"Message","description":"Human-readable error message"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit","description":"Applied request limit for the window"},"used":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Used","description":"Requests used in the current window"},"remaining":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Remaining","description":"Requests remaining in the current window"},"account_type":{"type":"string","title":"Account Type","description":"Resolved account type or fallback tier"},"reset_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Reset At","description":"ISO 8601 timestamp when the current window resets"},"contact":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contact","description":"Plan or support URL for resolving the limit"}},"type":"object","required":["error","message","account_type"],"title":"RateLimitErrorDetail","description":"Structured rate-limit error detail."},"RedditMarketSentimentDriver":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol","examples":["SPY"]},"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"Attributed mentions in the selected period, including inherited thread-context mentions","examples":[129]},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Asset buzz score in the selected period","examples":[74.1]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average sentiment score for this asset in the selected period","examples":[0.009]}},"type":"object","required":["ticker","mentions","buzz_score"],"title":"RedditMarketSentimentDriver","description":"Top asset contributing to the service-level Reddit market sentiment."},"RedditMarketSentimentResponse":{"properties":{"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Service-wide Reddit heat score relative to the service's trailing 90-day baseline. Around 50 = normal activity, higher values = hotter-than-usual service activity.","examples":[57.4]},"trend":{"anyOf":[{"type":"string","enum":["rising","falling","stable"]},{"type":"null"}],"title":"Trend","description":"Activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["stable"]},"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"Total Reddit mentions across the selected period, including inherited thread-context mentions","examples":[3992]},"unique_posts":{"type":"integer","minimum":0.0,"title":"Unique Posts","description":"Exact distinct Reddit post count across the selected UTC period","examples":[418]},"subreddit_count":{"type":"integer","minimum":0.0,"title":"Subreddit Count","description":"Distinct subreddits contributing in the selected period","examples":[21]},"total_upvotes":{"type":"integer","minimum":0.0,"title":"Total Upvotes","description":"Total upvotes across attributed mentions in the selected period","examples":[15234]},"active_tickers":{"type":"integer","minimum":0.0,"title":"Active Tickers","description":"Number of tickers with qualifying attributed Reddit activity in the selected period","examples":[1000]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Service-wide average sentiment score across all qualifying mentions in the selected period","examples":[0.045]},"positive_count":{"type":"integer","minimum":0.0,"title":"Positive Count","description":"Deprecated. Prefer bullish_pct with mentions for public analysis; retained for v1 compatibility.","deprecated":true,"examples":[1440]},"negative_count":{"type":"integer","minimum":0.0,"title":"Negative Count","description":"Deprecated. Prefer bearish_pct with mentions for public analysis; retained for v1 compatibility.","deprecated":true,"examples":[998]},"neutral_count":{"type":"integer","minimum":0.0,"title":"Neutral Count","description":"Deprecated. Prefer bullish_pct, bearish_pct and mentions for public analysis; retained for v1 compatibility.","deprecated":true,"examples":[1554]},"bullish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bullish Pct","description":"Bullish mention percentage","examples":[36]},"bearish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bearish Pct","description":"Bearish mention percentage","examples":[25]},"trend_history":{"items":{"type":"number"},"type":"array","title":"Trend History","description":"Daily service-wide buzz scores (oldest→newest) using the same relative baseline calibration. Length = max(requested_days, 7) for successful requests; windows before platform availability return HTTP 422.","examples":[[49.8,52.1,50.7,55.6,58.3,60.2,57.4]]},"drivers":{"items":{"$ref":"#/components/schemas/RedditMarketSentimentDriver"},"type":"array","title":"Drivers","description":"Top 5 stocks of the selected period by buzz_score. mentions and sentiment_score cover every day of the period."}},"type":"object","required":["buzz_score","mentions","unique_posts","subreddit_count","total_upvotes","active_tickers","positive_count","negative_count","neutral_count","bullish_pct","bearish_pct"],"title":"RedditMarketSentimentResponse","description":"Service-level Reddit market sentiment across all tracked stocks.","examples":[{"buzz_score":57.4,"trend":"stable","mentions":3992,"unique_posts":418,"subreddit_count":21,"total_upvotes":15234,"active_tickers":1000,"sentiment_score":0.045,"positive_count":1440,"negative_count":998,"neutral_count":1554,"bullish_pct":36,"bearish_pct":25,"trend_history":[49.8,52.1,50.7,55.6,58.3,60.2,57.4],"drivers":[{"ticker":"SPY","mentions":129,"buzz_score":74.1,"sentiment_score":0.009},{"ticker":"GOOGL","mentions":106,"buzz_score":71.8,"sentiment_score":0.029}]}]},"RedditRawMentionItem":{"properties":{"post_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Post Id","description":"Reddit post identifier","examples":["abc123"]},"comment_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Comment Id","description":"Reddit comment identifier when the mention comes from a comment","examples":["def456"]},"subreddit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subreddit","description":"Source subreddit","examples":["wallstreetbets"]},"author":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author","description":"Public Reddit author name, if scraped","examples":["deepfuckingvalue"]},"text_snippet":{"type":"string","title":"Text Snippet","description":"Stored mention snippet (truncated at ingestion time)","examples":["TSLA looks strong into earnings..."]},"created_utc":{"type":"string","format":"date-time","title":"Created Utc","description":"UTC timestamp of creation (ISO 8601)","examples":["2026-03-20T18:42:10Z"]},"upvotes":{"type":"integer","title":"Upvotes","description":"Reddit score (upvotes) for this mention row","examples":[381]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Sentiment score (-1 to +1)","examples":[0.62]},"sentiment_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sentiment Label","description":"Sentiment label (positive/negative/neutral)","examples":["positive"]},"is_inherited":{"type":"boolean","title":"Is Inherited","description":"Whether ticker context was inherited from the parent thread instead of directly mentioned","examples":[false]}},"type":"object","required":["text_snippet","created_utc","upvotes","is_inherited"],"title":"RedditRawMentionItem","description":"Raw Reddit mention row for one ticker."},"RedditRawMentionsResponse":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol","examples":["TSLA"]},"period_days":{"type":"integer","minimum":1.0,"title":"Period Days","description":"Lookback window used for the query","examples":[7]},"count":{"type":"integer","minimum":0.0,"title":"Count","description":"Total number of matching raw rows for the requested include_inherited filter before limit and offset are applied; only the requested page is returned","examples":[1]},"results":{"items":{"$ref":"#/components/schemas/RedditRawMentionItem"},"type":"array","title":"Results","description":"Raw mention rows ordered by newest first"}},"type":"object","required":["ticker","period_days","count","results"],"title":"RedditRawMentionsResponse","description":"Paginated raw Reddit mentions for a single ticker.","examples":[{"ticker":"TSLA","period_days":7,"count":1,"results":[{"post_id":"abc123","comment_id":"def456","subreddit":"wallstreetbets","author":"user123","text_snippet":"TSLA looks strong into earnings...","created_utc":"2026-03-20T18:42:10Z","upvotes":381,"sentiment_score":0.62,"sentiment_label":"positive","is_inherited":false}]}]},"RedditStatsResponse":{"properties":{"total_mentions":{"type":"integer","title":"Total Mentions","description":"All-time number of stored Reddit stock mentions","examples":[12833]},"unique_tickers":{"type":"integer","title":"Unique Tickers","description":"Number of unique tickers with mentions","examples":[65]},"mentions_today":{"type":"integer","title":"Mentions Today","description":"Stock mention rows created since today's UTC midnight, including posts, comments and inherited thread-context mentions","default":0,"examples":[342]},"unique_tickers_today":{"type":"integer","title":"Unique Tickers Today","description":"Unique tickers (detected using case-sensitive, uppercase-only patterns) including posts, comments and inherited thread-context mentions","default":0,"examples":[21]},"supported_tickers":{"type":"integer","title":"Supported Tickers","description":"Number of supported stock tickers","examples":[35000]}},"type":"object","required":["total_mentions","unique_tickers","supported_tickers"],"title":"RedditStatsResponse","description":"Service statistics.","examples":[{"total_mentions":12833,"unique_tickers":65,"mentions_today":342,"unique_tickers_today":21,"supported_tickers":35000}]},"RootHealthResponse":{"properties":{"status":{"type":"string","enum":["healthy","unhealthy"],"title":"Status","description":"Aggregated root health status","examples":["healthy"]},"service":{"type":"string","title":"Service","description":"Root service identifier","default":"adanos-api"},"version":{"type":"string","title":"Version","description":"Service version","examples":["1.53.4"]},"summary":{"$ref":"#/components/schemas/RootHealthSummary","description":"Aggregated health counts"},"services":{"additionalProperties":{"additionalProperties":true,"type":"object"},"type":"object","title":"Services","description":"Per-platform health payloads keyed by service identifier"}},"type":"object","required":["status","version","summary","services"],"title":"RootHealthResponse","description":"Root API health status aggregated across platforms.","examples":[{"status":"healthy","service":"adanos-api","version":"1.53.4","summary":{"total":5,"healthy":5,"unhealthy":0,"unhealthy_services":[]},"services":{"news-stocks":{"service":"news-stocks","status":"healthy","version":"1.53.4"},"polymarket-stocks":{"service":"polymarket-stocks","status":"healthy","version":"1.53.4"},"reddit-crypto":{"service":"reddit-crypto","status":"healthy","version":"1.53.4"},"reddit-stocks":{"service":"reddit-stocks","status":"healthy","version":"1.53.4"},"x-stocks":{"service":"x-stocks","status":"healthy","version":"1.53.4"}}}]},"RootHealthSummary":{"properties":{"total":{"type":"integer","title":"Total","description":"Number of platform health checks"},"healthy":{"type":"integer","title":"Healthy","description":"Number of checks that reported healthy"},"unhealthy":{"type":"integer","title":"Unhealthy","description":"Number of checks that reported unhealthy or timed out"},"unhealthy_services":{"items":{"type":"string"},"type":"array","title":"Unhealthy Services","description":"Service identifiers that reported unhealthy or timed out"}},"type":"object","required":["total","healthy","unhealthy","unhealthy_services"],"title":"RootHealthSummary","description":"Aggregated root health summary."},"SchedulerStatus":{"properties":{"running":{"type":"boolean","title":"Running","description":"Whether data collection is running"},"last_scrape":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Scrape","description":"ISO timestamp of last scrape (null if never run)"},"scrape_count":{"type":"integer","title":"Scrape Count","description":"Total number of scrapes performed","default":0},"error_count":{"type":"integer","title":"Error Count","description":"Total number of scrape errors/failures","default":0},"success_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Success Rate","description":"Scrape success rate (0.0-1.0)"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note","description":"Additional status information, for example why collection is not running"}},"type":"object","required":["running"],"title":"SchedulerStatus","description":"Scheduler status information.","examples":[{"running":true,"last_scrape":"2026-01-09T10:30:00Z","scrape_count":142,"error_count":3,"success_rate":0.979}]},"SearchResponse":{"properties":{"query":{"type":"string","title":"Query","description":"Original search query","examples":["tesla"]},"count":{"type":"integer","title":"Count","description":"Total number of matching results before the limit is applied","examples":[1]},"period_days":{"type":"integer","minimum":1.0,"title":"Period Days","description":"Fixed lookback window used for each summary block","examples":[7]},"results":{"items":{"$ref":"#/components/schemas/SearchResultItem"},"type":"array","title":"Results","description":"Top matching stocks capped by the requested limit"}},"type":"object","required":["query","count","period_days","results"],"title":"SearchResponse","description":"Search results for stocks.","examples":[{"query":"tesla","count":1,"period_days":7,"results":[{"ticker":"TSLA","name":"Tesla Inc.","type":"Stock","exchange":"NASDAQ","sector":"Consumer Discretionary","country":"United States","aliases":["Tesla","Elon"],"summary":{"mentions":342,"buzz_score":87.5,"trend":"rising","sentiment_score":0.23,"bearish_pct":18,"bullish_pct":45,"subreddit_count":8,"total_upvotes":15234,"unique_posts":45}}]}]},"SearchResultItem":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol","examples":["TSLA"]},"name":{"type":"string","title":"Name","description":"Company name","examples":["Tesla Inc."]},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type","description":"Asset type (Stock, ETF, etc.)","examples":["Stock"]},"exchange":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Exchange","description":"Stock exchange (NYSE, NASDAQ, etc.)","examples":["NASDAQ"]},"sector":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sector","description":"Industry sector","examples":["Consumer Discretionary"]},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"Country of headquarters","examples":["United States"]},"aliases":{"items":{"type":"string"},"type":"array","title":"Aliases","description":"Alternative names/aliases","examples":[["Tesla","Elon"]]},"summary":{"$ref":"#/components/schemas/StockSearchSummary","description":"Last-7-days Reddit summary for this asset"}},"type":"object","required":["ticker","name","summary"],"title":"SearchResultItem","description":"Individual search result item."},"SentimentAnalyzeRequest":{"properties":{"text":{"type":"string","maxLength":2048,"minLength":1,"title":"Text","description":"Financial text to analyze, for example a news headline or a sentence about a company.","examples":["Apple beats earnings estimates and raises its dividend"]},"target":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Target","description":"Optional: the company to judge the text for, as a name or ticker, for example `Apple` or `AAPL`. It should appear in the text; a company name works best. \"Goldman Sachs cuts Apple price target\" is negative for `Apple` and neutral for `Goldman Sachs`.","examples":["Apple"]}},"type":"object","required":["text"],"title":"SentimentAnalyzeRequest","description":"Direct text sentiment analysis request.","examples":[{"text":"Apple beats earnings estimates and raises its dividend","target":"Apple"}]},"SentimentAnalyzeResponse":{"properties":{"text":{"type":"string","title":"Text","description":"Normalized input text that was analyzed"},"sentiment_score":{"type":"number","maximum":1.0,"minimum":-1.0,"title":"Sentiment Score","description":"-1.0 bearish to +1.0 bullish","examples":[0.78]},"sentiment_label":{"type":"string","enum":["positive","neutral","negative"],"title":"Sentiment Label","description":"Adanos three-class sentiment label, matching top_mentions payloads","examples":["positive"]},"components":{"$ref":"#/components/schemas/SentimentComponents","description":"Whitelisted finance sentiment engine components"}},"type":"object","required":["text","sentiment_score","sentiment_label","components"],"title":"SentimentAnalyzeResponse","description":"Direct text sentiment analysis response.","examples":[{"text":"Apple beats earnings estimates and raises its dividend","sentiment_score":0.999,"sentiment_label":"positive","components":{"engine_version":"5.5","model_score":0.9988,"emoji_score":0.0,"phrase_adjustment":0.0,"phrase_matches":[],"contextual_finance_matches":[]}}]},"SentimentComponents":{"properties":{"engine_version":{"type":"string","title":"Engine Version","description":"Sentiment engine version","examples":["5.5"]},"model_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Model Score","description":"Raw model score from -1 to +1: the probability of positive minus the probability of negative. `sentiment_score` maps it onto the shared scale, where ±0.14 separates positive and negative from neutral.","examples":[0.9988]},"vader_compound":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Vader Compound","description":"Engine 5.4.1 only; since engine 5.5 it is null. VADER compound score after finance lexicon tuning.","deprecated":true},"roberta_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Roberta Score","description":"Engine 5.4.1 only; since engine 5.5 it is null; see `model_score`. RoBERTa ensemble score.","deprecated":true},"emoji_score":{"type":"number","maximum":1.0,"minimum":-1.0,"title":"Emoji Score","description":"Engine 5.4.1 only; since engine 5.5 it is 0. Emoji-derived sentiment score.","deprecated":true,"examples":[0.0]},"phrase_adjustment":{"type":"number","title":"Phrase Adjustment","description":"Engine 5.4.1 only; since engine 5.5 it is 0. Directional finance phrase adjustment.","deprecated":true,"examples":[0.0]},"phrase_matches":{"items":{"$ref":"#/components/schemas/SentimentPhraseMatch"},"type":"array","title":"Phrase Matches","description":"Engine 5.4.1 only; since engine 5.5 it is empty. Directional finance phrases matched by the engine.","deprecated":true},"contextual_finance_matches":{"items":{"type":"string"},"type":"array","title":"Contextual Finance Matches","description":"Engine 5.4.1 only; since engine 5.5 it is empty. Contextual finance phrases that informed scoring.","deprecated":true,"examples":[[]]}},"type":"object","required":["engine_version","emoji_score","phrase_adjustment"],"title":"SentimentComponents","description":"Whitelisted sentiment engine components exposed publicly."},"SentimentPhraseMatch":{"properties":{"phrase":{"type":"string","title":"Phrase","description":"Matched finance phrase","examples":["short squeeze"]},"score":{"type":"number","title":"Score","description":"Internal phrase sentiment score","examples":[3.5]}},"type":"object","required":["phrase","score"],"title":"SentimentPhraseMatch","description":"Whitelisted directional finance phrase metadata."},"StockExplanationResponse":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol","examples":["GME"]},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name","description":"Company name","examples":["Gamestop Corporation - Class A"]},"explanation":{"type":"string","title":"Explanation","description":"AI-generated explanation of why this stock is trending","examples":["GME is trending due to viral GameStop social media activity and large position posts on r/Superstonk."]},"cached":{"type":"boolean","title":"Cached","description":"Whether the explanation was served from cache","examples":[true]},"generated_at":{"type":"string","title":"Generated At","description":"Timezone-aware UTC ISO timestamp when explanation was generated","examples":["2026-01-13T14:30:00+00:00"]},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model","description":"LLM model used for generation","examples":["google/gemma-4-31B-it-turbo"]}},"type":"object","required":["ticker","explanation","cached","generated_at"],"title":"StockExplanationResponse","description":"AI-generated trend explanation for a stock.","examples":[{"ticker":"GME","company_name":"Gamestop Corporation - Class A","explanation":"GME is trending due to viral GameStop social media activity and large position posts on r/Superstonk.","cached":true,"generated_at":"2026-01-13T14:30:00+00:00","model":"google/gemma-4-31B-it-turbo"}]},"StockSearchSummary":{"properties":{"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"Attributed mentions in the last 7 UTC calendar days, including inherited thread-context mentions","examples":[342]},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Buzz score over the last 7 UTC calendar days","examples":[87.5]},"trend":{"anyOf":[{"type":"string","enum":["rising","falling","stable"]},{"type":"null"}],"title":"Trend","description":"Activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["rising"]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average sentiment score over the last 7 UTC calendar days","examples":[0.23]}},"type":"object","required":["mentions","buzz_score"],"title":"StockSearchSummary","description":"Compact last-7-days summary attached to stock search results."},"StockSentiment":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol","examples":["TSLA"]},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name","description":"Company name (null if unknown)","examples":["Tesla, Inc."]},"found":{"type":"boolean","title":"Found","description":"Legacy v1 data-availability flag. `true` means this service has qualifying data for this asset/window. `false` means the asset is supported, but this service has no qualifying data for the requested window. Planned for removal in v2.","deprecated":true},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Buzz Score (0-100). Asymptotic scaling above 50.","examples":[87.5]},"mentions":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Mentions","description":"Total attributed mentions in the selected period, including inherited thread-context mentions","examples":[342]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average sentiment score (-1 bearish to +1 bullish)","examples":[0.23]},"positive_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Positive Count","description":"Deprecated. Prefer bullish_pct with mentions for public analysis; retained for v1 compatibility.","deprecated":true,"examples":[154]},"negative_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Negative Count","description":"Deprecated. Prefer bearish_pct with mentions for public analysis; retained for v1 compatibility.","deprecated":true,"examples":[62]},"neutral_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Neutral Count","description":"Deprecated. Prefer bullish_pct, bearish_pct and mentions for public analysis; retained for v1 compatibility.","deprecated":true,"examples":[126]},"total_upvotes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Upvotes","description":"Total upvotes across attributed mentions","examples":[15234]},"unique_posts":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Unique Posts","description":"Number of unique posts","examples":[45]},"subreddit_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Subreddit Count","description":"Number of subreddits with mentions","examples":[8]},"trend":{"anyOf":[{"type":"string","enum":["rising","falling","stable"]},{"type":"null"}],"title":"Trend","description":"Activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["rising"]},"bullish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bullish Pct","description":"Percentage of bullish mentions","examples":[45]},"bearish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bearish Pct","description":"Percentage of bearish mentions","examples":[18]},"period_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Period Days","description":"Analysis period in days","examples":[7]},"top_subreddits":{"anyOf":[{"items":{"$ref":"#/components/schemas/SubredditCount"},"type":"array"},{"type":"null"}],"title":"Top Subreddits","description":"Top subreddits by attributed mention count"},"daily_trend":{"anyOf":[{"items":{"$ref":"#/components/schemas/DailyTrendItem"},"type":"array"},{"type":"null"}],"title":"Daily Trend","description":"Daily attributed mention breakdown for the selected period, with sentiment and buzz_score"},"top_mentions":{"anyOf":[{"items":{"$ref":"#/components/schemas/TopMention"},"type":"array"},{"type":"null"}],"title":"Top Mentions","description":"Top explicit mentions from the selected period, ranked by upvotes"}},"type":"object","required":["ticker","found"],"title":"StockSentiment","description":"Detailed sentiment analysis for a specific stock ticker.","examples":[{"ticker":"TSLA","company_name":"Tesla, Inc.","found":true,"buzz_score":87.5,"mentions":342,"sentiment_score":0.23,"total_upvotes":15234,"unique_posts":45,"subreddit_count":8,"trend":"rising","bullish_pct":45,"bearish_pct":18,"period_days":7,"top_subreddits":[{"subreddit":"wallstreetbets","mentions":89,"count":89},{"subreddit":"stocks","mentions":67,"count":67}],"daily_trend":[{"date":"2025-12-28","mentions":52,"sentiment_score":0.31,"buzz_score":42.8,"bullish_pct":58,"bearish_pct":19},{"date":"2025-12-27","mentions":48,"sentiment_score":0.18,"buzz_score":38.5,"bullish_pct":46,"bearish_pct":21}],"top_mentions":[{"text_snippet":"TSLA looking strong after...","sentiment_score":0.85,"sentiment_label":"positive","upvotes":1234,"subreddit":"wallstreetbets","created_utc":"2025-12-28T10:30:00Z"}]}]},"SubredditCount":{"properties":{"subreddit":{"type":"string","title":"Subreddit","description":"Subreddit name","examples":["wallstreetbets"]},"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"Attributed mentions in this subreddit","examples":[89]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average sentiment score for this subreddit in the selected period","examples":[0.31]},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Contributor-level buzz score for this subreddit in the selected period","examples":[64.2]},"count":{"type":"integer","minimum":0.0,"title":"Count","description":"Deprecated alias for mentions. Use mentions instead.","deprecated":true,"examples":[89]}},"type":"object","required":["subreddit","mentions","count"],"title":"SubredditCount","description":"Subreddit contributor metrics for a stock detail response."},"TopMention":{"properties":{"text_snippet":{"type":"string","title":"Text Snippet","description":"Clean Reddit paragraph around the detected ticker mention (up to 500 chars)","examples":["TSLA looking strong after..."]},"sentiment_score":{"type":"number","maximum":1.0,"minimum":-1.0,"title":"Sentiment Score","description":"Sentiment score (-1 to +1)","examples":[0.85]},"sentiment_label":{"type":"string","title":"Sentiment Label","description":"Sentiment label (positive/negative/neutral)","examples":["positive"]},"upvotes":{"type":"integer","title":"Upvotes","description":"Number of upvotes","examples":[1234]},"subreddit":{"type":"string","title":"Subreddit","description":"Source subreddit","examples":["wallstreetbets"]},"created_utc":{"type":"string","format":"date-time","title":"Created Utc","description":"UTC timestamp of creation (ISO 8601)","examples":["2025-12-28T10:30:00Z"]}},"type":"object","required":["text_snippet","sentiment_score","sentiment_label","upvotes","subreddit","created_utc"],"title":"TopMention","description":"Top mention by upvotes."},"TrendingCountry":{"properties":{"buzz_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Buzz Score","description":"Aggregated Buzz Score (0-100)","examples":[78.4]},"trend":{"type":"string","enum":["rising","falling","stable"],"title":"Trend","description":"Activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["rising"]},"mentions":{"type":"integer","title":"Mentions","description":"Total attributed mentions, including inherited thread-context mentions","examples":[4523]},"unique_tickers":{"type":"integer","title":"Unique Tickers","description":"Number of unique tickers mentioned","examples":[34]},"subreddit_count":{"type":"integer","title":"Subreddit Count","description":"Number of subreddits with mentions","examples":[15]},"sentiment_score":{"type":"number","maximum":1.0,"minimum":-1.0,"title":"Sentiment Score","description":"Weighted average sentiment (-1 bearish to +1 bullish)","examples":[0.28]},"bullish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bullish Pct","description":"Percentage of sentiment-labeled mentions that are bullish","examples":[54]},"bearish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bearish Pct","description":"Percentage of sentiment-labeled mentions that are bearish","examples":[22]},"total_upvotes":{"type":"integer","title":"Total Upvotes","description":"Total upvotes across attributed mentions","examples":[128450]},"trend_history":{"items":{"type":"number"},"type":"array","title":"Trend History","description":"Daily dimension buzz scores (oldest to newest). Length follows the resolved period, with a minimum of 7 values. Every slot describes only its UTC calendar day. The live final value describes today so far and can differ from period buzz_score. Closed historical windows end at `to`.","examples":[[45.2,48.1,52.3,55.0,58.2,61.5,78.4]]},"top_tickers":{"items":{"type":"string"},"type":"array","maxItems":5,"title":"Top Tickers","description":"Top 5 tickers by mentions","examples":[["NVDA","AAPL","MSFT","AMD","GOOGL"]]},"country":{"type":"string","title":"Country","description":"Country name","examples":["United States"]}},"type":"object","required":["buzz_score","trend","mentions","unique_tickers","subreddit_count","sentiment_score","bullish_pct","bearish_pct","total_upvotes","trend_history","top_tickers","country"],"title":"TrendingCountry","description":"Trending country with aggregated buzz metrics from Reddit.","examples":[{"buzz_score":82.3,"trend":"stable","mentions":8934,"unique_tickers":156,"subreddit_count":18,"sentiment_score":0.21,"bullish_pct":48,"bearish_pct":26,"total_upvotes":245000,"trend_history":[52.1,54.0,56.8,59.2,61.0,60.1,82.3],"top_tickers":["NVDA","TSLA","AAPL","AMD","PLTR"],"country":"United States"}]},"TrendingSector":{"properties":{"buzz_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Buzz Score","description":"Aggregated Buzz Score (0-100)","examples":[78.4]},"trend":{"type":"string","enum":["rising","falling","stable"],"title":"Trend","description":"Activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["rising"]},"mentions":{"type":"integer","title":"Mentions","description":"Total attributed mentions, including inherited thread-context mentions","examples":[4523]},"unique_tickers":{"type":"integer","title":"Unique Tickers","description":"Number of unique tickers mentioned","examples":[34]},"subreddit_count":{"type":"integer","title":"Subreddit Count","description":"Number of subreddits with mentions","examples":[15]},"sentiment_score":{"type":"number","maximum":1.0,"minimum":-1.0,"title":"Sentiment Score","description":"Weighted average sentiment (-1 bearish to +1 bullish)","examples":[0.28]},"bullish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bullish Pct","description":"Percentage of sentiment-labeled mentions that are bullish","examples":[54]},"bearish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bearish Pct","description":"Percentage of sentiment-labeled mentions that are bearish","examples":[22]},"total_upvotes":{"type":"integer","title":"Total Upvotes","description":"Total upvotes across attributed mentions","examples":[128450]},"trend_history":{"items":{"type":"number"},"type":"array","title":"Trend History","description":"Daily dimension buzz scores (oldest to newest). Length follows the resolved period, with a minimum of 7 values. Every slot describes only its UTC calendar day. The live final value describes today so far and can differ from period buzz_score. Closed historical windows end at `to`.","examples":[[45.2,48.1,52.3,55.0,58.2,61.5,78.4]]},"top_tickers":{"items":{"type":"string"},"type":"array","maxItems":5,"title":"Top Tickers","description":"Top 5 tickers by mentions","examples":[["NVDA","AAPL","MSFT","AMD","GOOGL"]]},"sector":{"type":"string","title":"Sector","description":"Industry sector name","examples":["Technology"]}},"type":"object","required":["buzz_score","trend","mentions","unique_tickers","subreddit_count","sentiment_score","bullish_pct","bearish_pct","total_upvotes","trend_history","top_tickers","sector"],"title":"TrendingSector","description":"Trending sector with aggregated buzz metrics from Reddit.","examples":[{"buzz_score":78.4,"trend":"rising","mentions":4523,"unique_tickers":34,"subreddit_count":15,"sentiment_score":0.28,"bullish_pct":54,"bearish_pct":22,"total_upvotes":128450,"trend_history":[45.2,48.1,52.3,55.0,58.2,61.5,78.4],"top_tickers":["NVDA","AAPL","MSFT","AMD","GOOGL"],"sector":"Technology"}]},"TrendingStock":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol","examples":["TSLA"]},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name","description":"Company name (null if unknown)","examples":["Tesla, Inc."]},"buzz_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Buzz Score","description":"Buzz Score (0-100). Asymptotic scaling above 50.","examples":[87.5]},"trend":{"type":"string","enum":["rising","falling","stable"],"title":"Trend","description":"Activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, upvotes and subreddit breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["rising"]},"mentions":{"type":"integer","title":"Mentions","description":"Total attributed mentions, including inherited thread-context mentions","examples":[342]},"unique_posts":{"type":"integer","title":"Unique Posts","description":"Number of unique posts","examples":[45]},"subreddit_count":{"type":"integer","title":"Subreddit Count","description":"Number of subreddits with mentions","examples":[8]},"sentiment_score":{"type":"number","maximum":1.0,"minimum":-1.0,"title":"Sentiment Score","description":"Average sentiment score (-1 bearish to +1 bullish)","examples":[0.23]},"bullish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bullish Pct","description":"Percentage of bullish mentions","examples":[45]},"bearish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bearish Pct","description":"Percentage of bearish mentions","examples":[18]},"total_upvotes":{"type":"integer","title":"Total Upvotes","description":"Total upvotes across attributed mentions","examples":[15234]},"trend_history":{"items":{"type":"number"},"type":"array","title":"Trend History","description":"Daily buzz scores (oldest→newest). Length follows the resolved period, with a minimum of 7 values. Values 0-100.","examples":[[12.3,15.2,18.7,22.1,28.5,35.2,42.8]]}},"type":"object","required":["ticker","buzz_score","trend","mentions","unique_posts","subreddit_count","sentiment_score","bullish_pct","bearish_pct","total_upvotes"],"title":"TrendingStock","description":"Trending stock with buzz metrics from Reddit.","examples":[{"ticker":"TSLA","company_name":"Tesla, Inc.","buzz_score":87.5,"trend":"rising","mentions":342,"unique_posts":45,"subreddit_count":8,"sentiment_score":0.23,"bullish_pct":45,"bearish_pct":18,"total_upvotes":15234,"trend_history":[45.2,52.1,48.7,67.3,72.1,78.4,87.5]}]},"UnsupportedAssetError":{"properties":{"detail":{"$ref":"#/components/schemas/UnsupportedAssetErrorDetail","description":"Structured unsupported asset details"}},"type":"object","required":["detail"],"title":"UnsupportedAssetError","description":"Error response for unsupported v1 stock/crypto asset requests."},"UnsupportedAssetErrorDetail":{"properties":{"error_code":{"type":"string","title":"Error Code","description":"Machine-readable unsupported asset error code","examples":["unsupported_ticker"]},"message":{"type":"string","title":"Message","description":"Human-readable unsupported asset message"}},"type":"object","required":["error_code","message"],"title":"UnsupportedAssetErrorDetail","description":"Structured detail for unsupported v1 stock/crypto asset requests."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Loc","description":"Location of the invalid input"},"msg":{"type":"string","title":"Msg","description":"Validation failure message"},"type":{"type":"string","title":"Type","description":"Validation error type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError","description":"FastAPI/Pydantic validation error item.","examples":[{"loc":["query","limit"],"msg":"Input should be greater than or equal to 1","type":"greater_than_equal"}]},"XCompareResponse":{"properties":{"period_days":{"type":"integer","title":"Period Days","description":"Analysis period in days","examples":[7]},"stocks":{"items":{"$ref":"#/components/schemas/XCompareStockItem"},"type":"array","title":"Stocks","description":"Stocks sorted by buzz_score descending"}},"type":"object","required":["period_days","stocks"],"title":"XCompareResponse","description":"Comparison response for multiple X/Twitter stocks.","examples":[{"period_days":7,"stocks":[{"ticker":"TSLA","company_name":"Tesla, Inc.","buzz_score":72.5,"trend":"rising","mentions":156,"unique_tweets":42,"sentiment_score":0.35,"bullish_pct":45,"bearish_pct":12,"total_upvotes":2847,"trend_history":[45.2,48.1,52.3,55.0,58.2,61.5,72.5]}]}]},"XCompareStockItem":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol","examples":["TSLA"]},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name","description":"Company name","examples":["Tesla, Inc."]},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Aggregated Buzz Score (0-100) from X mentions","examples":[72.5]},"trend":{"anyOf":[{"type":"string","enum":["rising","falling","stable"]},{"type":"null"}],"title":"Trend","description":"Activity momentum over the current 3 UTC days vs previous 3 UTC days, not price movement. Null when no qualifying X data exists.","examples":["rising"]},"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"Total tweet mentions","examples":[156]},"unique_tweets":{"type":"integer","minimum":0.0,"title":"Unique Tweets","description":"Number of unique tweets mentioning this ticker (distinct tweet_id)","examples":[42]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average sentiment score from tweet analysis (-1 to +1)","examples":[0.35]},"bullish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bullish Pct","description":"Percentage of bullish tweet mentions","examples":[45]},"bearish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bearish Pct","description":"Percentage of bearish tweet mentions","examples":[12]},"total_upvotes":{"type":"integer","minimum":0.0,"title":"Total Upvotes","description":"Total likes across all tweet mentions","examples":[2847]},"trend_history":{"items":{"type":"number"},"type":"array","title":"Trend History","description":"Daily buzz history (oldest to newest). Length follows the resolved period, with a minimum of 7 values when data exists. Closed historical windows end at `to`. Empty when no qualifying data exists.","examples":[[45.2,48.1,52.3,55.0,58.2,61.5,72.5]]}},"type":"object","required":["ticker","buzz_score","mentions","unique_tweets","total_upvotes"],"title":"XCompareStockItem","description":"Individual stock in X/Twitter comparison."},"XDailyTrendItem":{"properties":{"date":{"type":"string","title":"Date","description":"Date in YYYY-MM-DD format","examples":["2025-12-28"]},"mentions":{"type":"integer","title":"Mentions","description":"Number of tweet mentions on this date","examples":[42]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average sentiment score for the day","examples":[0.15]},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Buzz score for this date (0-100); null until the day is aggregated, while the activity fields are already filled","examples":[52.3]},"bullish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bullish Pct","description":"Bullish tweet percentage for this date, calculated from positive sentiment-classified tweets","examples":[60]},"bearish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bearish Pct","description":"Bearish tweet percentage for this date, calculated from negative sentiment-classified tweets","examples":[25]}},"type":"object","required":["date","mentions"],"title":"XDailyTrendItem","description":"Daily trend data point for X/Twitter."},"XHealthResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Current health status (healthy/unhealthy)","examples":["healthy"]},"service":{"type":"string","title":"Service","description":"Service identifier","examples":["x-stocks"]},"version":{"type":"string","title":"Version","description":"Current API version","examples":["1.53.4"]},"total_mentions":{"type":"integer","title":"Total Mentions","description":"Mentions observed in the most recent scrape cycle; returns 0 when scrape telemetry is unavailable.","examples":[15420]},"tickers_tracked":{"type":"integer","title":"Tickers Tracked","description":"Distinct tickers observed in the most recent scrape cycle; returns 0 when scrape telemetry is unavailable.","examples":[247]},"scheduler":{"anyOf":[{"$ref":"#/components/schemas/XSchedulerStatus"},{"type":"null"}],"description":"Data collection status"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message if unhealthy"}},"type":"object","required":["status","service","version","total_mentions","tickers_tracked"],"title":"XHealthResponse","description":"X/Twitter service health status - aligned with Reddit health response.","examples":[{"status":"healthy","service":"x-stocks","version":"1.53.4","total_mentions":15420,"tickers_tracked":247,"scheduler":{"running":true,"last_scrape":"2025-12-31T06:00:00Z","scrape_count":42,"error_count":2,"success_rate":0.95}}]},"XMarketSentimentDriver":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol","examples":["TSLA"]},"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"Tweet mentions in the selected period","examples":[156]},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Asset buzz score in the selected period","examples":[72.5]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average tweet sentiment score for this asset","examples":[0.35]}},"type":"object","required":["ticker","mentions","buzz_score"],"title":"XMarketSentimentDriver","description":"Top asset contributing to the service-level X market sentiment."},"XMarketSentimentResponse":{"properties":{"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Service-wide X/Twitter heat score relative to the service's trailing 90-day baseline. Around 50 = normal activity, higher values = hotter-than-usual X activity.","examples":[56.2]},"trend":{"anyOf":[{"type":"string","enum":["rising","falling","stable"]},{"type":"null"}],"title":"Trend","description":"Activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, likes and author breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["rising"]},"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"Tweet mentions across the selected period","examples":[2847]},"unique_tweets":{"type":"integer","minimum":0.0,"title":"Unique Tweets","description":"Exact distinct tweet count across the selected UTC period","examples":[913]},"unique_authors":{"type":"integer","minimum":0.0,"title":"Unique Authors","description":"Exact distinct author breadth across the selected UTC period","examples":[604]},"total_upvotes":{"type":"integer","minimum":0.0,"title":"Total Upvotes","description":"Total likes across the selected period","examples":[28471]},"active_tickers":{"type":"integer","minimum":0.0,"title":"Active Tickers","description":"Number of tickers with X activity in the selected period","examples":[442]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Service-wide average tweet sentiment score","examples":[0.081]},"positive_count":{"type":"integer","minimum":0.0,"title":"Positive Count","description":"Deprecated. Prefer bullish_pct with mentions for public analysis; retained for v1 compatibility.","deprecated":true,"examples":[1198]},"negative_count":{"type":"integer","minimum":0.0,"title":"Negative Count","description":"Deprecated. Prefer bearish_pct with mentions for public analysis; retained for v1 compatibility.","deprecated":true,"examples":[741]},"neutral_count":{"type":"integer","minimum":0.0,"title":"Neutral Count","description":"Deprecated. Prefer bullish_pct, bearish_pct and mentions for public analysis; retained for v1 compatibility.","deprecated":true,"examples":[908]},"bullish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bullish Pct","description":"Bullish tweet percentage","examples":[42]},"bearish_pct":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Bearish Pct","description":"Bearish tweet percentage","examples":[26]},"trend_history":{"items":{"type":"number"},"type":"array","title":"Trend History","description":"Daily service-wide buzz scores (oldest→newest) using the same relative baseline calibration. Length = max(requested_days, 7) for successful requests; windows before platform availability return HTTP 422.","examples":[[48.9,50.7,52.6,54.4,57.1,58.3,56.2]]},"drivers":{"items":{"$ref":"#/components/schemas/XMarketSentimentDriver"},"type":"array","title":"Drivers","description":"Top 5 stocks of the selected period by buzz_score. mentions and sentiment_score cover every day of the period."}},"type":"object","required":["buzz_score","mentions","unique_tweets","unique_authors","total_upvotes","active_tickers","positive_count","negative_count","neutral_count","bullish_pct","bearish_pct"],"title":"XMarketSentimentResponse","description":"Service-level X/Twitter market sentiment across all tracked stocks.","examples":[{"buzz_score":56.2,"trend":"rising","mentions":2847,"unique_tweets":913,"unique_authors":604,"total_upvotes":28471,"active_tickers":442,"sentiment_score":0.081,"positive_count":1198,"negative_count":741,"neutral_count":908,"bullish_pct":42,"bearish_pct":26,"trend_history":[48.9,50.7,52.6,54.4,57.1,58.3,56.2],"drivers":[{"ticker":"TSLA","mentions":156,"buzz_score":72.5,"sentiment_score":0.35},{"ticker":"NVDA","mentions":141,"buzz_score":70.8,"sentiment_score":0.27}]}]},"XRawMentionItem":{"properties":{"tweet_id":{"type":"string","title":"Tweet Id","description":"Tweet identifier","examples":["1901234567890"]},"author":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author","description":"Public X/Twitter username, if scraped","examples":["marketwatcher"]},"text_snippet":{"type":"string","maxLength":280,"title":"Text Snippet","description":"Tweet text snippet","examples":["$NVDA still has room after the pullback..."]},"created_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created Utc","description":"Tweet creation time in UTC (ISO 8601) when available","examples":["2026-03-20T14:11:02Z"]},"likes":{"type":"integer","minimum":0.0,"title":"Likes","description":"Number of likes","examples":[942]},"retweets":{"type":"integer","minimum":0.0,"title":"Retweets","description":"Number of retweets","examples":[88]},"views":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Views","description":"Number of views","examples":[52110]},"is_reply":{"type":"boolean","title":"Is Reply","description":"Whether this row comes from a reply tweet","examples":[false]},"parent_tweet_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Tweet Id","description":"Parent tweet identifier for replies","examples":["1900000000000"]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Sentiment score (-1 to +1)","examples":[0.44]},"sentiment_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sentiment Label","description":"Sentiment label (positive/negative/neutral)","examples":["positive"]}},"type":"object","required":["tweet_id","text_snippet","likes","retweets","is_reply"],"title":"XRawMentionItem","description":"Raw tweet mention row for one stock ticker."},"XRawMentionsResponse":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol","examples":["NVDA"]},"period_days":{"type":"integer","minimum":1.0,"title":"Period Days","description":"Lookback window used for the query","examples":[7]},"count":{"type":"integer","minimum":0.0,"title":"Count","description":"Total number of matching raw rows before limit and offset are applied; only the requested page is returned","examples":[1]},"results":{"items":{"$ref":"#/components/schemas/XRawMentionItem"},"type":"array","title":"Results","description":"Raw tweet rows ordered by newest first"}},"type":"object","required":["ticker","period_days","count","results"],"title":"XRawMentionsResponse","description":"Paginated raw tweet mentions for a single stock ticker.","examples":[{"ticker":"NVDA","period_days":7,"count":1,"results":[{"tweet_id":"1901234567890","author":"marketwatcher","text_snippet":"$NVDA still has room after the pullback...","created_utc":"2026-03-20T14:11:02Z","likes":942,"retweets":88,"views":52110,"is_reply":false,"sentiment_score":0.44,"sentiment_label":"positive"}]}]},"XSchedulerStatus":{"properties":{"running":{"type":"boolean","title":"Running","description":"Whether data collection is running (reported within the last 90 minutes)","examples":[true]},"last_scrape":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Scrape","description":"ISO timestamp of last completed scrape cycle"},"scrape_count":{"type":"integer","title":"Scrape Count","description":"Total completed scrape cycles since worker start","default":0},"error_count":{"type":"integer","title":"Error Count","description":"Total failed scrape cycles","default":0},"success_rate":{"type":"number","title":"Success Rate","description":"Success rate (success_count / scrape_count)","default":0.0,"examples":[0.95]},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note","description":"Additional status info (e.g., worker crash warning)"}},"type":"object","required":["running"],"title":"XSchedulerStatus","description":"X/Twitter data collection status.","examples":[{"running":true,"last_scrape":"2025-12-31T06:00:00Z","scrape_count":42,"error_count":2,"success_rate":0.95}]},"XSearchResponse":{"properties":{"query":{"type":"string","title":"Query","description":"Original search query","examples":["tesla"]},"count":{"type":"integer","title":"Count","description":"Total number of matching results before the limit is applied","examples":[1]},"period_days":{"type":"integer","minimum":1.0,"title":"Period Days","description":"Fixed lookback window used for each summary block","examples":[7]},"results":{"items":{"$ref":"#/components/schemas/XSearchResultItem"},"type":"array","title":"Results","description":"Top matching stocks capped by the requested limit"}},"type":"object","required":["query","count","period_days","results"],"title":"XSearchResponse","description":"Search response for X/Twitter stocks.","examples":[{"query":"tesla","count":1,"period_days":7,"results":[{"ticker":"TSLA","name":"Tesla Inc.","type":"Stock","exchange":"NASDAQ","sector":"Consumer Discretionary","country":"United States","aliases":["Tesla","Elon"],"summary":{"mentions":156,"buzz_score":72.5,"trend":"rising","sentiment_score":0.35}}]}]},"XSearchResultItem":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol","examples":["TSLA"]},"name":{"type":"string","title":"Name","description":"Company name","examples":["Tesla Inc."]},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type","description":"Asset type (Stock, ETF, etc.)","examples":["Stock"]},"exchange":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Exchange","description":"Stock exchange","examples":["NASDAQ"]},"sector":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sector","description":"Industry sector","examples":["Consumer Discretionary"]},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"Country of headquarters","examples":["United States"]},"aliases":{"items":{"type":"string"},"type":"array","title":"Aliases","description":"Alternative names/aliases","examples":[["Tesla","Elon"]]},"summary":{"$ref":"#/components/schemas/XSearchSummary","description":"Last-7-days X summary for this asset"}},"type":"object","required":["ticker","name","summary"],"title":"XSearchResultItem","description":"Individual X/Twitter search result item."},"XSearchSummary":{"properties":{"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"Tweet mentions in the last 7 UTC calendar days","examples":[156]},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Buzz score over the last 7 UTC calendar days","examples":[72.5]},"trend":{"anyOf":[{"type":"string","enum":["rising","falling","stable"]},{"type":"null"}],"title":"Trend","description":"Activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, likes and author breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["rising"]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average sentiment score over the last 7 UTC calendar days","examples":[0.35]}},"type":"object","required":["mentions","buzz_score"],"title":"XSearchSummary","description":"Compact last-7-days summary attached to X search results."},"XStatsResponse":{"properties":{"total_mentions":{"type":"integer","title":"Total Mentions","description":"All-time number of stored X mentions","default":0},"unique_tickers":{"type":"integer","title":"Unique Tickers","description":"Number of unique tickers with X mentions in the database","default":0},"mentions_today":{"type":"integer","title":"Mentions Today","description":"X mention rows created since today's UTC midnight","default":0},"unique_tickers_today":{"type":"integer","title":"Unique Tickers Today","description":"Unique tickers with X mentions since today's UTC midnight","default":0},"supported_tickers":{"type":"integer","title":"Supported Tickers","description":"Number of supported stock tickers","default":0}},"type":"object","title":"XStatsResponse","description":"X/Twitter service statistics.","examples":[{"total_mentions":935,"unique_tickers":100,"mentions_today":42,"unique_tickers_today":12,"supported_tickers":35000}]},"XStockDetailResponse":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol"},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name","description":"Company name"},"found":{"type":"boolean","title":"Found","description":"Legacy v1 data-availability flag. `true` means this service has qualifying data for this asset/window. `false` means the asset is supported, but this service has no qualifying data for the requested window. Planned for removal in v2.","default":true,"deprecated":true},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Buzz score (0-100) from tweet activity, including author diversity (null if not found)"},"mentions":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Mentions","description":"Total tweet mentions within the selected period","examples":[156]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average sentiment score from tweet analysis (-1 to +1)"},"positive_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Positive Count","description":"Deprecated. Prefer bullish_pct with mentions for public analysis; retained for v1 compatibility.","deprecated":true},"negative_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Negative Count","description":"Deprecated. Prefer bearish_pct with mentions for public analysis; retained for v1 compatibility.","deprecated":true},"neutral_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Neutral Count","description":"Deprecated. Prefer bullish_pct, bearish_pct and mentions for public analysis; retained for v1 compatibility.","deprecated":true},"total_upvotes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Upvotes","description":"Total likes across all tweet mentions"},"unique_tweets":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Unique Tweets","description":"Number of unique tweets (distinct tweet_id)"},"trend":{"anyOf":[{"type":"string","enum":["rising","falling","stable"]},{"type":"null"}],"title":"Trend","description":"Activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, likes and author breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["rising"]},"bullish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bullish Pct","description":"Percentage of bullish tweet mentions","examples":[45]},"bearish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bearish Pct","description":"Percentage of bearish tweet mentions","examples":[12]},"period_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Period Days","description":"Analysis period in days"},"daily_trend":{"anyOf":[{"items":{"$ref":"#/components/schemas/XDailyTrendItem"},"type":"array"},{"type":"null"}],"title":"Daily Trend","description":"Daily mention breakdown for the selected period"},"top_tweets":{"anyOf":[{"items":{"$ref":"#/components/schemas/XTopTweet"},"type":"array","maxItems":10},{"type":"null"}],"title":"Top Tweets","description":"Top tweets from the selected period, ranked by engagement (likes + retweets)"},"top_authors":{"anyOf":[{"items":{"$ref":"#/components/schemas/XTopAuthor"},"type":"array","maxItems":5},{"type":"null"}],"title":"Top Authors","description":"Top X authors in the selected period with mentions, sentiment_score, buzz_score and deprecated count alias"}},"type":"object","required":["ticker"],"title":"XStockDetailResponse","description":"Detailed X/Twitter data for a single stock, in the same format as the Reddit API.","examples":[{"ticker":"TSLA","company_name":"Tesla, Inc.","found":true,"buzz_score":72.5,"mentions":156,"sentiment_score":0.35,"total_upvotes":2847,"unique_tweets":42,"trend":"rising","bullish_pct":45,"bearish_pct":12,"period_days":7,"daily_trend":[{"date":"2025-12-28","mentions":42,"sentiment_score":0.15,"buzz_score":52.3,"bullish_pct":60,"bearish_pct":25},{"date":"2025-12-27","mentions":38,"sentiment_score":0.22,"buzz_score":48.1,"bullish_pct":55,"bearish_pct":18}],"top_tweets":[{"text_snippet":"$TSLA breaking out! 🚀","sentiment_score":0.85,"sentiment_label":"positive","likes":1247,"retweets":89,"views":52340,"author":"stockguru","created_at":"2025-12-28T14:32:00Z"}],"top_authors":[{"author":"stockguru","mentions":24,"sentiment_score":0.41,"buzz_score":61.8,"count":24}]}]},"XTopAuthor":{"properties":{"author":{"type":"string","title":"Author","description":"Public X/Twitter username","examples":["marketwatcher"]},"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"Tweet mentions by this author in the selected period","examples":[72]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average sentiment score for this author's mentions in the selected period","examples":[0.18]},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Contributor-level buzz score for this author in the selected period","examples":[67.3]},"count":{"type":"integer","minimum":0.0,"title":"Count","description":"Deprecated alias for mentions. Use mentions instead.","deprecated":true,"examples":[72]}},"type":"object","required":["author","mentions","count"],"title":"XTopAuthor","description":"X author contributor metrics for a stock detail response."},"XTopTweet":{"properties":{"text_snippet":{"type":"string","maxLength":280,"title":"Text Snippet","description":"Clean tweet paragraph around the detected ticker mention (truncated to 280 chars for this view)","examples":["$TSLA breaking out! This is the move we've been waiting for 🚀"]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Sentiment score (-1 to +1)","examples":[0.85]},"sentiment_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sentiment Label","description":"Sentiment label (positive/negative/neutral)","examples":["positive"]},"likes":{"type":"integer","minimum":0.0,"title":"Likes","description":"Number of likes","examples":[1247]},"retweets":{"type":"integer","minimum":0.0,"title":"Retweets","description":"Number of retweets","examples":[89]},"views":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Views","description":"Number of views","examples":[52340]},"author":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author","description":"Author username","examples":["elonmusk"]},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At","description":"Tweet creation time (ISO 8601)","examples":["2025-12-28T14:32:00Z"]}},"type":"object","required":["text_snippet","likes","retweets"],"title":"XTopTweet","description":"Top tweet mention for a stock - highest engagement tweets.","examples":[{"text_snippet":"$TSLA breaking out! This is the move we've been waiting for 🚀","sentiment_score":0.85,"sentiment_label":"positive","likes":1247,"retweets":89,"views":52340,"author":"elonmusk","created_at":"2025-12-28T14:32:00Z"}]},"XTrendingCountry":{"properties":{"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Aggregated Buzz Score (0-100) from X mentions","examples":[78.4]},"trend":{"type":"string","enum":["rising","falling","stable"],"title":"Trend","description":"Activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, likes and author breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["rising"]},"mentions":{"type":"integer","title":"Mentions","description":"Total tweet mentions","examples":[4523]},"unique_tickers":{"type":"integer","title":"Unique Tickers","description":"Number of unique tickers mentioned","examples":[34]},"unique_authors":{"type":"integer","title":"Unique Authors","description":"Exact distinct author breadth across the selected UTC period","examples":[156]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Weighted average sentiment (-1 bearish to +1 bullish)","examples":[0.28]},"bullish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bullish Pct","description":"Percentage of bullish mentions","examples":[54]},"bearish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bearish Pct","description":"Percentage of bearish mentions","examples":[22]},"total_upvotes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Upvotes","description":"Total likes across all mentions","examples":[128450]},"trend_history":{"items":{"type":"number"},"type":"array","title":"Trend History","description":"Daily dimension buzz scores (oldest to newest). Length follows the resolved period, with a minimum of 7 values. Every slot describes only its UTC calendar day. The live final value describes today so far and can differ from period buzz_score. Closed historical windows end at `to`. Historical author breadth is rebuilt from daily author_distribution where available and may conservatively approximate exact cross-ticker author de-duplication.","examples":[[45.2,48.1,52.3,55.0,58.2,61.5,78.4]]},"top_tickers":{"items":{"type":"string"},"type":"array","maxItems":5,"title":"Top Tickers","description":"Top 5 tickers by mention count in this dimension","examples":[["NVDA","AAPL","MSFT","AMD","GOOGL"]]},"country":{"type":"string","title":"Country","description":"Country name","examples":["United States"]}},"type":"object","required":["buzz_score","trend","mentions","unique_tickers","unique_authors","trend_history","top_tickers","country"],"title":"XTrendingCountry","description":"Trending country with aggregated buzz metrics from X/Twitter.","examples":[{"buzz_score":82.3,"trend":"stable","mentions":8934,"unique_tickers":156,"unique_authors":423,"sentiment_score":0.21,"bullish_pct":48,"bearish_pct":26,"total_upvotes":245000,"trend_history":[52.1,54.0,56.8,59.2,61.0,60.1,82.3],"top_tickers":["NVDA","TSLA","AAPL","AMD","PLTR"],"country":"United States"}]},"XTrendingSector":{"properties":{"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Aggregated Buzz Score (0-100) from X mentions","examples":[78.4]},"trend":{"type":"string","enum":["rising","falling","stable"],"title":"Trend","description":"Activity momentum over the current 3 UTC days vs previous 3 UTC days using mentions, likes and author breadth; not price movement. For `from`/`to`, anchors at `to` (or now when `to` is today).","examples":["rising"]},"mentions":{"type":"integer","title":"Mentions","description":"Total tweet mentions","examples":[4523]},"unique_tickers":{"type":"integer","title":"Unique Tickers","description":"Number of unique tickers mentioned","examples":[34]},"unique_authors":{"type":"integer","title":"Unique Authors","description":"Exact distinct author breadth across the selected UTC period","examples":[156]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Weighted average sentiment (-1 bearish to +1 bullish)","examples":[0.28]},"bullish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bullish Pct","description":"Percentage of bullish mentions","examples":[54]},"bearish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bearish Pct","description":"Percentage of bearish mentions","examples":[22]},"total_upvotes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Upvotes","description":"Total likes across all mentions","examples":[128450]},"trend_history":{"items":{"type":"number"},"type":"array","title":"Trend History","description":"Daily dimension buzz scores (oldest to newest). Length follows the resolved period, with a minimum of 7 values. Every slot describes only its UTC calendar day. The live final value describes today so far and can differ from period buzz_score. Closed historical windows end at `to`. Historical author breadth is rebuilt from daily author_distribution where available and may conservatively approximate exact cross-ticker author de-duplication.","examples":[[45.2,48.1,52.3,55.0,58.2,61.5,78.4]]},"top_tickers":{"items":{"type":"string"},"type":"array","maxItems":5,"title":"Top Tickers","description":"Top 5 tickers by mention count in this dimension","examples":[["NVDA","AAPL","MSFT","AMD","GOOGL"]]},"sector":{"type":"string","title":"Sector","description":"Industry sector name","examples":["Technology"]}},"type":"object","required":["buzz_score","trend","mentions","unique_tickers","unique_authors","trend_history","top_tickers","sector"],"title":"XTrendingSector","description":"Trending sector with aggregated buzz metrics from X/Twitter.","examples":[{"buzz_score":78.4,"trend":"rising","mentions":4523,"unique_tickers":34,"unique_authors":156,"sentiment_score":0.28,"bullish_pct":54,"bearish_pct":22,"total_upvotes":128450,"trend_history":[45.2,48.1,52.3,55.0,58.2,61.5,78.4],"top_tickers":["NVDA","AAPL","MSFT","AMD","GOOGL"],"sector":"Technology"}]},"XTrendingStock":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol","examples":["TSLA"]},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name","description":"Company name","examples":["Tesla, Inc."]},"buzz_score":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Buzz Score","description":"Buzz score from tweet activity. Components: mentions (20), sentiment (20), quality (10), author diversity (14) and trend (-10 to +20). Asymptotic scaling caps at 100.","examples":[72.5]},"trend":{"type":"string","enum":["rising","falling","stable"],"title":"Trend","description":"Activity momentum over the current 3 UTC days vs previous 3 UTC days, not price movement.","examples":["rising"]},"mentions":{"type":"integer","minimum":0.0,"title":"Mentions","description":"Number of tweets mentioning the ticker","examples":[156]},"sentiment_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":-1.0},{"type":"null"}],"title":"Sentiment Score","description":"Average sentiment score from tweet analysis (-1 to +1)","examples":[0.35]},"bullish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bullish Pct","description":"Percentage of bullish tweet mentions","examples":[45]},"bearish_pct":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Bearish Pct","description":"Percentage of bearish tweet mentions","examples":[12]},"total_upvotes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Upvotes","description":"Total likes across all tweet mentions","examples":[2847]},"unique_tweets":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Unique Tweets","description":"Number of unique tweets mentioning this ticker (distinct tweet_id)","examples":[42]},"trend_history":{"items":{"type":"number"},"type":"array","title":"Trend History","description":"Daily buzz scores (oldest→newest). Length follows the resolved period, with a minimum of 7 values. For live windows, the final value is the current live buzz_score; closed historical windows end at `to`.","examples":[[45.2,48.1,52.3,55.0,58.2,61.5,64.8]]}},"type":"object","required":["ticker","buzz_score","trend","mentions"],"title":"XTrendingStock","description":"Trending stock on X/Twitter, in the same format as the Reddit API.\n\nMetrics come from tweets and replies that mention the ticker. Author\ndiversity rewards discussion spread across many accounts.","examples":[{"ticker":"TSLA","company_name":"Tesla, Inc.","buzz_score":72.5,"trend":"rising","mentions":156,"sentiment_score":0.35,"bullish_pct":45,"bearish_pct":12,"total_upvotes":2847,"unique_tweets":42,"trend_history":[45.2,48.1,52.3,55.0,58.2,61.5,64.8]}]}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","description":"API key for authentication.\n\nGet your API key at https://adanos.org/register.\n\nFormat: `sk_live_` followed by 32 hexadecimal characters. Example: `sk_live_0123456789abcdef0123456789abcdef`.","in":"header","name":"X-API-Key"}}},"tags":[{"name":"Reddit Stocks","description":"Stock discussion from posts and comments in investing subreddits. A reply without a ticker inherits the ticker of its thread. Start with `/trending`, then open `/stock/{ticker}` or track a watchlist with `/compare`."},{"name":"Reddit Crypto","description":"Token discussion from posts and comments in crypto subreddits. It mirrors Reddit Stocks, with `/token/{symbol}` in place of `/stock/{ticker}` and without the sector, country and AI explanation endpoints."},{"name":"X/Twitter Stocks","description":"Stock discussion on X/Twitter, collected from cashtag tweets and their replies. Likes are reported as `total_upvotes`."},{"name":"Polymarket Stocks","description":"Stock-related prediction markets on Polymarket. Signals come from trades, prices, liquidity and order books. Activity is counted in trades and markets (`trade_count`, `market_count`)."},{"name":"News Stocks","description":"Stock coverage in financial news articles. `source_count` shows how many outlets reported. `source` filters by publisher. News identifies companies, so use `BRK` where other platforms take `BRK.B`."},{"name":"Health-Check","description":"Public status endpoints. No API key needed. Each one reports whether its platform is collecting data and when it last did."},{"name":"Finance Sentiment","description":"Scores the sentiment of financial text you send, such as a headline or a sentence about a company. Uses Adanos News Sentiment 5.5. Professional plan."}]}