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

Calendar events

GET /calendar-events
ListCalendarEvents

Upcoming and past market events (earnings, economic releases, IPOs, listings, votes, hearings), globally or for one asset or subject, with type, status, importance from 1 to 3, and the entities involved. Defaults to today onward, earliest first; send min_importance_score=2 for the notable ones.

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/calendar-events. 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:50

offset integer QUERY

Number of results skipped.

Default:0

start_time_after string (date-time) QUERY

Only events 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 events starting before this RFC3339 time. Free plans reach back 90 days; further returns 403.

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

domains array<string> QUERY

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

Example:equities,macro

event_types array<string> QUERY

Keep events of any of these types. Send several comma-separated.

Example:earnings,economic_release

statuses array<string> QUERY

Keep events in any of these statuses. Send several comma-separated.

Example:scheduled,postponed

min_importance_score integer QUERY

Minimum importance from 1 (low) to 3 (high). Defaults to 1, which includes every event.

Default:1

cURL Example

curl --request GET \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/calendar-events' \
  --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

calendar_events
array<object> required

Calendar events matching the supplied filters.
calendar_events[].calendar_event_id
string required

Stable public identifier for the calendar event.

calendar_events[].confidence_score
integer required

Confidence in the event, from 1 (low) to 10 (high).

calendar_events[].created_at
string (date-time) required

UTC time when the record was created.

calendar_events[].domains
array<string> required

Market or subject domains attached to the record.

calendar_events[].end_time
string (date-time) optional

UTC event end time when known.

calendar_events[].entities
array<object> required

Assets and non-asset subjects linked to this record.
calendar_events[].entities[].asset_class
string optional

The asset's class, sent with asset_id.

Allowed values
equitycommodityindexcrypto
calendar_events[].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.

calendar_events[].entities[].confidence
number (float) optional

Entity-link confidence when available.

calendar_events[].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.

calendar_events[].entities[].is_primary
boolean required

True when this is the record's primary linked entity.

calendar_events[].entities[].name
string required

Human-readable name.

calendar_events[].entities[].role
string required

Relationship of the linked entity to the calendar event.

calendar_events[].entities[].subject_id
string optional

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

calendar_events[].event_metadata
object optional

Event-type-specific structured metadata. Keys vary by event type.

calendar_events[].event_subtype
string optional

More specific event classification when available.

calendar_events[].event_type
string required

High-level event classification.

calendar_events[].importance_score
integer required

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

calendar_events[].location
string optional

Where the event physically takes place, when a place is known. Absent for online and on-chain events.

calendar_events[].long_term_impact_score
integer required

Estimated long-term market impact, from 1 (low) to 3 (high).

calendar_events[].macro_impact_score
integer required

Estimated macroeconomic impact, from 1 (low) to 3 (high).

calendar_events[].price_impact_score
integer required

Estimated direct price impact, from 1 (low) to 3 (high).

calendar_events[].short_term_impact_score
integer required

Estimated short-term market impact, from 1 (low) to 3 (high).

calendar_events[].source_count
integer required

Number of sources supporting the event.

calendar_events[].sources
array<object> required

Source records supporting the parent response.
calendar_events[].sources[].external_id
string required

Identifier assigned by the external source.

calendar_events[].sources[].provider
string optional

Upstream data provider when available.

calendar_events[].sources[].published_at
string (date-time) required

UTC publication time.

calendar_events[].sources[].publisher
string optional

Original publisher when available.

calendar_events[].sources[].source
string required

Source platform or feed.

calendar_events[].sources[].subtype
string required

Source subtype.

calendar_events[].sources[].trusted
boolean required

Whether the source is classified as trusted.

calendar_events[].sources[].url
string optional

Public source URL when available.

calendar_events[].start_time
string (date-time) required

UTC time when the intelligence item or event starts.

calendar_events[].status
string required

Current lifecycle status of the event: scheduled, tentative, cancelled, or postponed.

calendar_events[].summary
string optional

Evidence-grounded summary of the intelligence item.

calendar_events[].tags
array<string> required

Searchable labels attached to the record.

calendar_events[].tail_risk_impact_score
integer required

Estimated tail-risk impact, from 1 (low) to 3 (high).

calendar_events[].time_precision
string required

Precision of the published event time: minute, hour, day, week, month, year, or unknown. A day-precision event starts at 00:00 UTC that day.

calendar_events[].title
string required

Human-readable event title.

calendar_events[].trusted_source_count
integer required

Number of supporting sources marked trusted.

calendar_events[].updated_at
string (date-time) required

UTC time when the record was last updated.

{
  "calendar_events": [
    {
      "calendar_event_id": "earnings:nvda:2026-q3",
      "confidence_score": 9,
      "created_at": "2026-08-06T10:00:00Z",
      "domains": [
        "equities",
        "technology"
      ],
      "end_time": "2026-08-20T21:00:00Z",
      "entities": [
        {
          "asset_class": "equity",
          "asset_id": "NVDA",
          "confidence": 0.98,
          "entity_id": "eq:NVDA",
          "is_primary": true,
          "name": "NVIDIA Corporation",
          "role": "affected",
          "subject_id": "text:jensen huang"
        }
      ],
      "event_metadata": {
        "fiscal_quarter": "Q3",
        "fiscal_year": 2026
      },
      "event_subtype": "quarterly_results",
      "event_type": "earnings",
      "importance_score": 3,
      "location": "Santa Clara, California",
      "long_term_impact_score": 2,
      "macro_impact_score": 1,
      "price_impact_score": 3,
      "short_term_impact_score": 3,
      "source_count": 4,
      "sources": [
        {
          "external_id": "0001045810-26-000123",
          "provider": "SEC EDGAR",
          "published_at": "2026-08-07T14:30:00Z",
          "publisher": "NVIDIA Corporation",
          "source": "sec",
          "subtype": "filing",
          "trusted": true,
          "url": "https://www.sec.gov/Archives/edgar/data/1045810/example.htm"
        }
      ],
      "start_time": "2026-08-20T20:00:00Z",
      "status": "scheduled",
      "summary": "Management raised guidance after stronger-than-expected data-centre demand.",
      "tags": [
        "earnings",
        "data_centres"
      ],
      "tail_risk_impact_score": 1,
      "time_precision": "exact",
      "title": "NVIDIA Q3 2026 earnings",
      "trusted_source_count": 3,
      "updated_at": "2026-08-07T14:35:00Z"
    }
  ]
}