# Sentiment by timeframe

- Method: `GET`
- Path: `/sentiment/timeframes`
- Tier: Pro
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/get-sentiment-timeframes/
- Interactive docs: https://docs.hiddensystems.ai/nebula/api/#endpoint=get-sentiment-timeframes

## Description

Returns short-, medium-, and long-horizon sentiment series and current readings for exactly one resolved asset or non-asset subject. Asset selectors support equities, commodities, indices, and crypto assets returned by GET /assets; commodity and index IDs use asset_class=equity. Parameter rules: One of asset_id or subject_id is required. asset_id requires asset_class. subject_id and asset_class cannot be combined. subject_id and asset_id cannot be combined.

## cURL Example

```bash
curl --get \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/sentiment/timeframes' \
  --data-urlencode 'asset_id=NVDA' \
  --data-urlencode 'asset_class=equity' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## Path Parameters

No path parameters for this endpoint.

## Query Parameters

- `asset_id` (string, optional): Canonical identifier returned by /assets. Stock, commodity, and index IDs are normally ticker or market symbols and use asset_class=equity; crypto IDs are canonical crypto slugs. asset_class is mandatory whenever asset_id is present.
- `asset_class` (string, optional, allowed: equity, crypto): Namespace of asset_id, or the market class for endpoints with a class-scoped global view. Stocks, commodities, and indices use equity. Equity is the documented default only where the endpoint description states a default.
- `subject_id` (string, optional): Canonical non-asset identifier returned by /subjects. It cannot be combined with asset_id or asset_class.
- `hours` (integer, optional, default: 720): Lookback window in hours.
- `granularity` (string, optional, allowed: 1h, 2h, 4h, 12h, 1d): Requested time-series bucket size. When omitted, the service chooses a bucket size appropriate for the lookback window.

## Response

OK

- `current` (object, required, allowed keys: short_term, medium_term, long_term): Latest sentiment reading for each available timeframe horizon.
- `metadata` (object): Methodology and request-window metadata needed to interpret the response.
- `metadata.as_of` (string (date-time)): UTC time at which the metric was calculated.
- `metadata.calculation` (string): Short name for the calculation method.
- `metadata.formula` (string): Human-readable formula for the calculation.
- `metadata.half_life_hours` (number (double)): Exponential-decay half-life used by the calculation, in hours.
- `metadata.lookback_days` (integer): Historical lookback used by the calculation, in days.
- `metadata.scale` (string): Published scale or interpretation of the metric.
- `series` (object, required, allowed keys: short_term, medium_term, long_term): Sentiment series keyed by short_term, medium_term, and long_term horizon.
- `series.{key}[].interval_posts` (number (double)): Posts in this emitted time bucket, before lookback accumulation.
- `series.{key}[].sentiment_signal` (number (double), required): Decay-weighted net bullish posts: bullish minus bearish. Positive is bullish, negative is bearish, and magnitude grows with activity.
- `series.{key}[].timestamp` (string (date-time), required): UTC RFC 3339 timestamp for the observation or bucket start.
- `series.{key}[].total_posts` (number (double)): Post count over the metric's active lookback window.

Media type: `application/json`

## JSON Response

```json
{
  "current": {
    "long_term": 52.1,
    "medium_term": 57.8,
    "short_term": 64.2
  },
  "series": {
    "short_term": [
      {
        "sentiment_signal": 64.2,
        "timestamp": "2026-08-07T15:00:00Z",
        "total_posts": 318
      }
    ]
  }
}
```