# Calendar events

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

## Description

Returns market events globally or for exactly one resolved asset or non-asset subject. By default, the global response starts at the current UTC day; use time bounds to request history. 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/calendar-events' \
  --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, default: 50): Maximum results returned.
- `offset` (integer, optional, default: 0): Number of results skipped.
- `start_time_after` (string (date-time), optional): Only events starting after this RFC3339 time.
- `start_time_before` (string (date-time), optional): Only events starting before this RFC3339 time.
- `domains` (string, optional): Comma-separated domains.
- `event_types` (string, optional): Comma-separated event types.
- `statuses` (string, optional): Comma-separated event statuses.
- `min_importance_score` (integer, optional): Minimum importance score. Defaults to 3; use 1 to include routine events.

## Response

OK

- `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 score assigned by the event pipeline.
- `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)): UTC event end time when known.
- `calendar_events[].entities` (array<object>, required): Assets and non-asset subjects linked to this record.
- `calendar_events[].entities[].confidence` (number (float)): Entity-link confidence when available.
- `calendar_events[].entities[].entity_id` (string, required): Canonical knowledge-graph identifier for the linked entity. Use /assets or /subjects to resolve request selectors.
- `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[].event_metadata` (object): Event-type-specific structured metadata. Keys vary by event type.
- `calendar_events[].event_subtype` (string): More specific event classification when available.
- `calendar_events[].event_type` (string, required): High-level event classification.
- `calendar_events[].importance_score` (integer, required): Relative importance score from 1 to 10.
- `calendar_events[].long_term_impact_score` (integer, required): Estimated long-term market impact score.
- `calendar_events[].macro_impact_score` (integer, required): Estimated macroeconomic impact score.
- `calendar_events[].price_impact_score` (integer, required): Estimated direct price-impact score.
- `calendar_events[].short_term_impact_score` (integer, required): Estimated short-term market impact score.
- `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): Upstream data provider when available.
- `calendar_events[].sources[].published_at` (string (date-time), required): UTC publication time.
- `calendar_events[].sources[].publisher` (string): 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): 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.
- `calendar_events[].summary` (string): 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 score.
- `calendar_events[].time_precision` (string, required): Precision of the published event time.
- `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.

Media type: `application/json`

## JSON Response

```json
{
  "calendar_events": [
    {
      "calendar_event_id": "earnings:nvda:2026-q3",
      "confidence_score": 96,
      "created_at": "2026-08-06T10:00:00Z",
      "domains": [
        "equities",
        "technology"
      ],
      "end_time": "2026-08-20T21:00:00Z",
      "entities": [
        {
          "confidence": 0.98,
          "entity_id": "eq:NVDA",
          "is_primary": true,
          "name": "NVIDIA Corporation",
          "role": "affected"
        }
      ],
      "event_metadata": {
        "fiscal_quarter": "Q3",
        "fiscal_year": 2026
      },
      "event_subtype": "quarterly_results",
      "event_type": "earnings",
      "importance_score": 8,
      "long_term_impact_score": 7,
      "macro_impact_score": 5,
      "price_impact_score": 9,
      "short_term_impact_score": 8,
      "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": 3,
      "time_precision": "exact",
      "title": "NVIDIA Q3 2026 earnings",
      "trusted_source_count": 3,
      "updated_at": "2026-08-07T14:35:00Z"
    }
  ]
}
```