Docs home All endpoints Interactive docs Markdown OpenAPI JSON

Handles sentiment

GET /handles/sentiment

Starter

Description

Aggregated sentiment for author handles. Provide up to 5 handles and/or one tag. Supported tags: watchlist, top_callers, top_crypto_kols, top_celebrities. Optionally pass token_id to filter sentiment to posts related to a specific token (accepts internal token_id or coingecko_id). Hours lookback is capped at 2160 (90d). Non-watchlist tags are snapshot-backed by day for backtest-safe historical queries. Returns 400 for invalid hours, invalid tag, invalid token_id, missing snapshots for the requested lookback window, more than one tag, more than 5 handles, missing handles/tags, or an empty watchlist selection. Note: /sentiment/handles is a deprecated alias and will be removed after 30 days.

Path Parameters

No path parameters for this endpoint.

Query Parameters

handles
stringoptional

Author handles as comma-separated list or repeated query param (max 5 total).

tags
stringoptional

Optional single tag (one value only): watchlist, top_callers, top_crypto_kols, or top_celebrities.

token_id
stringoptional

Optional token filter. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).

hours
integeroptional

Lookback window in hours.

granularity
stringoptionalenum: 1h, 2h, 4h, 12h, 1d

Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.

Responses

OK

Media type: application/json

handles
array<string> optional

Normalized handles included in the aggregation set.

summary
array<object> optional

Aggregate sentiment time series across the selected handles.

summary[].bearish_posts
number (double) optional

Count of bearish posts included in the computed window.

summary[].bucket_start
string (date-time) optional

UTC bucket start timestamp.

summary[].bullish_posts
number (double) optional

Count of bullish posts included in the computed window.

summary[].interval_bearish_posts
number (double) optional

Bearish posts in the current emitted interval bucket.

summary[].interval_bullish_posts
number (double) optional

Bullish posts in the current emitted interval bucket.

summary[].interval_neutral_posts
number (double) optional

Neutral posts in the current emitted interval bucket.

summary[].interval_posts
number (double) optional

Posts in the current emitted interval bucket.

summary[].neutral_posts
number (double) optional

Count of neutral posts included in the computed window.

summary[].sentiment_score
number (double) optional

Sentiment score on a 0-100 scale (higher is more bullish).

summary[].sentiment_score_smoothed
number (double) optional

Smoothed sentiment score (0-100) when available.

summary[].sentiment_score_z
number (double) optional

Z-score normalized sentiment where available.

summary[].sentiment_signal
number (double) optional

Model-level sentiment signal used for downstream ranking when available.

summary[].total_posts
number (double) optional

Total posts included in the computed window.

summary[].total_posts_smoothed
number (double) optional

Smoothed total-posts series where available.

tags
array<string> optional

Applied selector tag(s) used to build the handle set.