Docs home All endpoints Interactive docs Markdown OpenAPI JSON

Handles sentiment

GET /handles/sentiment
GetHandlesSentiment

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.

Parameters

handles string QUERY

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

Example:milesdeutscher,hsakatrades

tags string QUERY

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

Example:top_callers

token_id string QUERY

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

Example:string

hours integer QUERY

Lookback window in hours.

Example:168

granularity string QUERY

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

Allowed values
1h2h4h12h1d

Example:1h

Responses

200 OK
400 Bad Request ErrorResponse

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.