All docs Nebula docs All endpoints Interactive docs Markdown OpenAPI JSON
  1. REST API
  2. Intelligence

Intelligence

GET /insights
ListInsights

Short stories on what is happening in markets, globally or for one asset or subject, each with a headline, summary, sentiment (−1, 0, or +1), tags, importance from 1 to 3, and the entities involved. Most recently updated first; send order_by=start_time_desc for the newest events first.

Parameter rules:

  • Send asset_class and asset_id together, or neither.
  • subject_id cannot be combined with asset_id or asset_class.

Wallet payment available at https://nebula-api.hiddensystems.ai/api/v1/x402/insights. No Nebula account or API key required; check the payment offer before signing. x402 payment guide.

Parameters

asset_id string QUERY

Asset ID from /assets or /search, such as NVDA, GLD, SPX, or bitcoin. Send it with the asset_class returned alongside it.

Example:NVDA

asset_class string QUERY

Class of the asset named by asset_id: equity (stocks and ETFs), commodity, index, or crypto. Send the asset_class that /assets or /search returned alongside the asset_id.

Allowed values
equitycommodityindexcrypto

Example:equity

subject_id string QUERY

Canonical non-asset identifier returned by /subjects or /search, such as text:jensen huang or handle:elonmusk. Accepted in any case. It cannot be combined with asset_id or asset_class.

Example:text:jensen huang

limit integer QUERY

Maximum results returned.

Default:10

offset integer QUERY

Number of results skipped.

Default:0

start_time_after string (date-time) QUERY

Only items starting after this RFC3339 time. Free plans reach back 90 days; further returns 403.

Example:2026-08-01T00:00:00Z

start_time_before string (date-time) QUERY

Only items starting before this RFC3339 time. Free plans reach back 90 days; further returns 403.

Example:2026-08-07T00:00:00Z

tags array<string> QUERY

Keep stories carrying any of these tags, matched exactly (for example earnings). Tags are free-form labels; read them off returned stories. Send several comma-separated.

Example:earnings

exclude_tags array<string> QUERY

Leave out stories carrying any of these tags. It matches tags only, not categories or domains: to leave out crypto stories, filter domains instead. Send several comma-separated.

Example:rumour

categories array<string> QUERY

Keep stories whose primary category is one of these, matched exactly (for example equities or technology). Categories are free-form; read them off returned stories. Send several comma-separated.

Example:equities

domains array<string> QUERY

Keep stories in any of these domains. Send several comma-separated.

Example:equities,macro

order_by string QUERY

Result ordering. Defaults to updated_at_desc.

Allowed values
start_time_ascstart_time_descupdated_at_ascupdated_at_desccreated_at_asccreated_at_descimportance_score_ascimportance_score_desc

Default:updated_at_desc

cURL Example

curl --request GET \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/insights' \
  --header 'X-API-Key: YOUR_API_KEY'

Responses

200 OK
400 Bad Request
401 Unauthorized
402 Credits used up; response includes renewal timing and purchased credit balance
403 Forbidden
404 Not Found
405 Method not allowed; the Allow header lists the supported method
429 Too Many Requests
500 Internal Server Error
503 Service Unavailable

Media type application/json

insights
array<object> required

Curated intelligence items matching the supplied filters.
insights[].category
string optional

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[].asset_class
string optional

The asset's class, sent with asset_id.

Allowed values
equitycommodityindexcrypto
insights[].entities[].asset_id
string optional

For a stock, commodity, index, or coin, the asset_id the asset endpoints take; absent for people, accounts, and topics, and for the rare asset Nebula cannot place.

insights[].entities[].entity_id
string required

Nebula's id for the linked entity, such as eq:NVDA, gecko:1, or text:ai. To query the entity, use asset_id and asset_class, or subject_id, from the same object.

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[].entities[].subject_id
string optional

For a person, account, or topic, the subject_id the subject-aware endpoints take; absent for assets.

insights[].headline
string required

Concise intelligence headline.

insights[].importance_score
integer required

Importance from 1 (low) to 3 (high).

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) optional

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) optional

UTC time when the record was last updated.

{
  "insights": [
    {
      "category": "earnings",
      "domains": [
        "equities",
        "technology"
      ],
      "entities": [
        {
          "asset_class": "equity",
          "asset_id": "NVDA",
          "entity_id": "eq:NVDA",
          "entity_types": [
            "equity"
          ],
          "is_direct": true,
          "is_primary": true,
          "name": "NVIDIA Corporation",
          "role": "primary",
          "subject_id": "text:jensen huang"
        }
      ],
      "headline": "NVIDIA raises its quarterly revenue outlook",
      "importance_score": 3,
      "insight_id": 38421,
      "sentiment_score": 1,
      "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"
    }
  ]
}