> ## Documentation Index
> Fetch the complete documentation index at: https://docs.financialdatapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Economic calendar & official events

> Scheduled macro releases and official central bank events with source provenance, plus one unified feed across macro releases, central-bank actions, and issuer filings.

Financial Data API dates the macro world. The economic calendar gives you scheduled and released macro events with the values consumers expect on a calendar (actual, forecast, consensus, previous, and revised). The unified events feed merges that calendar with every other official event Financial Data API tracks (central-bank actions and issuer filings) into one normalized shape with a single schema.

<Columns cols={2}>
  <Card title="Economic calendar" icon="calendar-days" href="#the-economic-calendar">
    `GET /economic-calendar` is the scheduled macro-release calendar: CPI prints, payrolls, central-bank meetings, each with actual, forecast, consensus, previous, and revised values.
  </Card>

  <Card title="Unified official events" icon="layer-group" href="#unified-official-events">
    `GET /events` is one stream across macro releases, central-bank actions, and issuer filings, with a single normalized event shape.
  </Card>
</Columns>

<Info>
  Use the calendar when you want classic macro-release rows with surprise inputs and release-time semantics. Use the unified events feed when you want a single stream across event classes (macro releases plus central-bank actions and issuer filings) under one schema.
</Info>

## What data is available

The calendar covers the same canonical macro indicators Financial Data API normalizes (CPI, core CPI, PCE, PPI, unemployment, nonfarm payrolls, jobless claims, real GDP growth, policy rates, money-market and government-bond yields, housing starts, building permits, trade balance, exports, imports, personal income, retail sales) across the covered countries, sourced from the institutions of record (FRED, BLS, ECB, OECD, BIS, Eurostat, Bank of England, Bank of Japan, and more). Read the live indicator list from `GET /canonical-indicators` and the country and category breadth from `GET /coverage`.

The unified events feed spans three event families:

<Columns cols={3}>
  <Card title="Macro releases" icon="chart-line">
    Scheduled and released macro prints, the same rows the economic calendar carries, surfaced as `macro_release` events.
  </Card>

  <Card title="Central-bank actions" icon="landmark">
    Policy decisions and meetings from the central banks Financial Data API tracks, surfaced as `central_bank` events.
  </Card>

  <Card title="Issuer filings" icon="building-columns">
    SEC EDGAR filings from the company universe, surfaced as `issuer_filing` events. The structured statements behind them live in the [financial statements](/apis/financial-statements) endpoint.
  </Card>
</Columns>

<Tip>
  Coverage grows over time. Read live breadth from `GET /coverage` and the live indicator slugs from `GET /canonical-indicators` rather than hard-coding which events exist.
</Tip>

<Note>
  Both feeds are rights-aware. Every event carries an `exposure` class, and only redistribution-safe events appear where the public surface applies. Licensed vendor data never appears on the public surface.
</Note>

## Authentication

Send your key as `x-api-key` (or `Authorization: Bearer`). Both endpoints require the `data:read` scope. See [Authentication](/authentication).

## The economic calendar

`GET /economic-calendar` returns scheduled and released macro events. Each row carries the release time, the period it covers, and the value series: actual, forecast, consensus, previous, and (where applicable) revised.

### Filters

The calendar accepts the standard list filters plus the observation filters relevant to events. Unknown query parameters are rejected with `bad_request`.

### Example: high-importance US releases

<CodeGroup>
  ```bash cURL theme={"theme":"css-variables"}
  curl "https://api.financialdatapi.com/economic-calendar?country=USA&importance=high&limit=5&order=desc" \
    -H "x-api-key: $FINANCIALDATA_API_KEY"
  ```

  ```typescript TypeScript (@financialdatapi/client) theme={"theme":"css-variables"}
  import { FinancialDataApiClient } from "@financialdatapi/client";

  const client = new FinancialDataApiClient({ apiKey: process.env.FINANCIALDATA_API_KEY! });

  const { data } = await client.economicCalendar({
    country: "USA",
    importance: "high",
    limit: 5,
    order: "desc",
  });

  for (const event of data) {
    console.log(event.releaseTime, event.eventName, event.actualValue, event.forecastValue);
  }
  ```
</CodeGroup>

```json Response theme={"theme":"css-variables"}
{
  "data": [
    {
      "id": "ecal_us_cpi_2026_05",
      "providerEventId": "...",
      "sourceId": "bls",
      "providerId": "bls",
      "entityId": "country_usa",
      "countryIso3": "USA",
      "indicatorId": "cpi_inflation_yoy",
      "eventName": "CPI (YoY)",
      "eventType": "economic_release",
      "importance": "high",
      "status": "released",
      "releaseTime": "2026-06-11T12:30:00Z",
      "releaseTimeZone": "America/New_York",
      "period": "2026-05",
      "periodStart": "2026-05-01",
      "periodEnd": "2026-05-31",
      "actualValue": 3.1,
      "forecastValue": 3.2,
      "consensusValue": 3.2,
      "previousValue": 3.3,
      "revisedValue": null,
      "unit": "percent",
      "currency": null,
      "sourceUrl": "https://www.bls.gov/...",
      "attribution": "U.S. Bureau of Labor Statistics",
      "observationId": "obs_...",
      "exposure": "public"
    }
  ],
  "meta": {
    "api_version": "v1",
    "pagination": { "limit": 5, "cursor": null, "next_cursor": null, "has_more": false }
  },
  "requestId": "..."
}
```

<Note>
  Example figures above are illustrative. Pull live values from the endpoint.
</Note>

### Calendar event fields

### Get a single calendar event

`GET /economic-calendar/{id}` returns one calendar event by its `id`.

<CodeGroup>
  ```bash cURL theme={"theme":"css-variables"}
  curl "https://api.financialdatapi.com/economic-calendar/ecal_us_cpi_2026_05" \
    -H "x-api-key: $FINANCIALDATA_API_KEY"
  ```

  ```typescript TypeScript (@financialdatapi/client) theme={"theme":"css-variables"}
  const { data: event } = await client.request(
    "/economic-calendar/ecal_us_cpi_2026_05"
  );
  console.log(event.eventName, event.actualValue);
  ```
</CodeGroup>

## First-release vs revised

Macro series are revised after their first print. Financial Data API keeps both, and the calendar exposes the distinction so you can model surprises honestly.

<AccordionGroup>
  <Accordion title="previousValue is first-release basis" defaultOpen icon="clock-rotate-left">
    `previousValue` carries the prior period value as it was known at this release, not the latest revised figure. That is what a forecast was measured against at the time, so it is the correct base for surprise and momentum calculations.
  </Accordion>

  <Accordion title="revisedValue and status: revised" icon="pen-to-square">
    When an event reports a revision, `revisedValue` is populated and `status` is `revised`. The original `actualValue` is preserved. Revisions are retained, never overwritten in place.
  </Accordion>

  <Accordion title="Reconstructing what was known at a point in time" icon="hourglass">
    To see the value set as known on a given date, use the knowledge-time filters (`start_date` and `end_date`) and `as_of` on the observations API. Honest caveat: `as_of` currently approximates the ingestion timestamp, not full provider-vintage reconstruction. Full vintage reconstruction is future work.
  </Accordion>
</AccordionGroup>

## Unified official events

`GET /events` merges the economic calendar with every other official event into one normalized response shape. It covers macro releases, central-bank actions, and issuer filings (for example SEC filings) under one schema. Use it when you want a single stream and one set of fields across event classes.

### Filters

### Example: released US macro events

<CodeGroup>
  ```bash cURL theme={"theme":"css-variables"}
  curl "https://api.financialdatapi.com/events?event_class=macro_release&country=USA&status=released&limit=5" \
    -H "x-api-key: $FINANCIALDATA_API_KEY"
  ```

  ```typescript TypeScript (@financialdatapi/client) theme={"theme":"css-variables"}
  import { FinancialDataApiClient } from "@financialdatapi/client";

  const client = new FinancialDataApiClient({ apiKey: process.env.FINANCIALDATA_API_KEY! });

  const { data } = await client.officialEvents({
    event_class: "macro_release",
    country: "USA",
    status: "released",
    limit: 5,
  });

  for (const event of data) {
    console.log(event.eventClass, event.eventType, event.title, event.observedAt);
  }
  ```
</CodeGroup>

```json Response theme={"theme":"css-variables"}
{
  "data": [
    {
      "id": "obs_or_ecal_id",
      "canonicalEventId": "...",
      "eventClass": "macro_release",
      "eventType": "economic_release",
      "eventLabel": "CPI (YoY)",
      "eventStatus": "released",
      "entityId": "country_usa",
      "countryIso3": "USA",
      "indicatorId": "cpi_inflation_yoy",
      "observedAt": "2026-06-11T12:30:00Z",
      "releasedAt": "2026-06-11T12:30:00Z",
      "effectiveAt": null,
      "periodStart": "2026-05-01",
      "periodEnd": "2026-05-31",
      "title": "CPI (YoY)",
      "summary": null,
      "tags": ["economic_release", "USA", "cpi_inflation_yoy"],
      "sourceId": "bls",
      "providerId": "bls",
      "sourceUrl": "https://www.bls.gov/...",
      "attribution": "U.S. Bureau of Labor Statistics",
      "exposure": "public",
      "linkedObservationId": "obs_...",
      "metadata": {
        "importance": "high",
        "actualValue": 3.1,
        "forecastValue": 3.2,
        "consensusValue": 3.2,
        "previousValue": 3.3,
        "revisedValue": null,
        "unit": "percent",
        "currency": null
      }
    }
  ],
  "meta": {
    "api_version": "v1",
    "pagination": { "limit": 5, "cursor": null, "next_cursor": null, "has_more": false }
  },
  "requestId": "..."
}
```

### Unified event fields

### Get a single event

`GET /events/{id}` returns one unified event by its `id`.

<CodeGroup>
  ```bash cURL theme={"theme":"css-variables"}
  curl "https://api.financialdatapi.com/events/obs_or_ecal_id" \
    -H "x-api-key: $FINANCIALDATA_API_KEY"
  ```

  ```typescript TypeScript (@financialdatapi/client) theme={"theme":"css-variables"}
  const { data: event } = await client.request("/events/obs_or_ecal_id");
  console.log(event.title, event.eventStatus);
  ```
</CodeGroup>

## Calendar vs unified events: which to use

<Columns cols={2}>
  <Card title="Use the economic calendar" icon="calendar-check">
    You want macro-release rows with surprise inputs (actual, forecast, consensus, previous, revised) and release-time semantics. Filter by `country`, `indicator`, `importance`, `status`, `event_type`, and `period`.
  </Card>

  <Card title="Use unified events" icon="diagram-project">
    You want one stream across event classes (macro releases plus central-bank actions and issuer filings) under a single schema. Filter by `event_class`, `event_type`, `status`, `exposure`, and time.
  </Card>
</Columns>

## Related

<CardGroup cols={2}>
  <Card title="Macro observations" icon="chart-line" href="/apis/macro-indicators">
    Follow `observationId` (or `linkedObservationId`) to the point-in-time value the event released, with full filters and provenance.
  </Card>

  <Card title="Financial statements" icon="building-columns" href="/apis/financial-statements">
    Issuer filings surface as `issuer_filing` events here; the structured statements behind them live in the financials endpoint.
  </Card>

  <Card title="Derived analytics" icon="function" href="/apis/derived-analytics">
    Surprise indices and other analytics are computed from calendar inputs and stored as derived observations.
  </Card>
</CardGroup>