# Intelligence

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

## Description

Returns curated intelligence globally or for exactly one resolved asset or non-asset subject. The unscoped response spans all supported asset classes and subjects. Asset selectors support equities, commodities, indices, and crypto assets returned by GET /assets; commodity and index IDs use asset_class=equity. Parameter rules: asset_class requires asset_id. 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 --request GET \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/insights' \
  --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.
- `limit` (integer, optional): Maximum results returned.
- `offset` (integer, optional): Number of results skipped.
- `start_time_after` (string (date-time), optional): Only items starting after this RFC3339 time.
- `start_time_before` (string (date-time), optional): Only items starting before this RFC3339 time.
- `tags` (string, optional): Comma-separated tags.
- `exclude_tags` (string, optional): Comma-separated excluded tags.
- `categories` (string, optional): Comma-separated categories.
- `domains` (string, optional): Comma-separated domains.
- `order_by` (string, optional, default: updated_at_desc, allowed: start_time_asc, start_time_desc, updated_at_asc, updated_at_desc, created_at_asc, created_at_desc, importance_score_asc, importance_score_desc): Result ordering. Defaults to updated_at_desc.

## Response

OK

- `insights` (array<object>, required): Curated intelligence items matching the supplied filters.
- `insights[].category` (string): Primary intelligence category when assigned.
- `insights[].domains` (array<string>, required): Market or subject domains attached to the record.
- `insights[].entities` (array<object>, required): Assets and non-asset subjects linked to this record.
- `insights[].entities[].entity_id` (string, required): Canonical knowledge-graph identifier for the linked entity. Use /assets or /subjects to resolve request selectors.
- `insights[].entities[].entity_types` (array<string>, required): Knowledge-graph classifications for the linked entity.
- `insights[].entities[].is_direct` (boolean, required): True when the record directly concerns this linked entity.
- `insights[].entities[].is_primary` (boolean, required): True when this is the record's primary linked entity.
- `insights[].entities[].name` (string, required): Human-readable name.
- `insights[].entities[].role` (string, required): Relationship of the linked entity to the intelligence item.
- `insights[].headline` (string, required): Concise intelligence headline.
- `insights[].importance_score` (integer, required): Relative importance score from 1 to 10.
- `insights[].insight_id` (integer (int64), required): Stable identifier for the intelligence item.
- `insights[].sentiment_score` (integer, required): Signed sentiment score; positive is bullish and negative is bearish.
- `insights[].start_time` (string (date-time)): UTC time when the intelligence item or event starts.
- `insights[].summary` (string, required): Evidence-grounded summary of the intelligence item.
- `insights[].tags` (array<string>, required): Searchable labels attached to the record.
- `insights[].updated_at` (string (date-time)): UTC time when the record was last updated.

Media type: `application/json`

## JSON Response

```json
{
  "insights": [
    {
      "category": "earnings",
      "domains": [
        "equities",
        "technology"
      ],
      "entities": [
        {
          "entity_id": "eq:NVDA",
          "entity_types": [
            "equity"
          ],
          "is_direct": true,
          "is_primary": true,
          "name": "NVIDIA Corporation",
          "role": "primary"
        }
      ],
      "headline": "NVIDIA raises its quarterly revenue outlook",
      "importance_score": 8,
      "insight_id": 38421,
      "sentiment_score": 61,
      "start_time": "2026-08-20T20:00:00Z",
      "summary": "Management raised guidance after stronger-than-expected data-centre demand.",
      "tags": [
        "earnings",
        "data_centres"
      ],
      "updated_at": "2026-08-07T14:35:00Z"
    }
  ]
}
```