Economic events API

Sign in, open the developer dashboard, and create an API key. Its secret is displayed once, so copy it before leaving the page. An active Growth or Enterprise subscription is required to create and use keys. Then use the development base URL below, or replace it with your deployed origin.

curl --get 'http://localhost:8080/api/v1/events' \
  --header 'Authorization: Bearer es_test_your_key' \
  --data-urlencode 'from=2026-08-10T00:00:00Z' \
  --data-urlencode 'to=2026-08-12T23:59:59Z' \
  --data-urlencode 'currency=USD' \
  --data-urlencode 'limit=100'

Every /api/v1/events request requires an active EconStream API key. Send it as a bearer token (recommended) or in the X-API-Key header.

Authorization: Bearer es_live_...

# Alternative
X-API-Key: es_live_...

{
  "id": "6d4e83c2-c7de-4f19-b456-139cb46ccd7c",
  "scheduledAt": "2026-08-11T08:30:00.000Z",
  "currency": "USD",
  "countryCode": "US",
  "category": "Employment",
  "importance": "HIGH",
  "eventName": "Nonfarm Payrolls (Jul)",
  "previous": "173K",
  "forecast": "170K",
  "actual": "216K",
  "unit": "K",
  "sourceName": "Bureau of Labor Statistics",
  "sourceUrl": "https://www.bls.gov/",
  "summary": "Monthly change in nonfarm employment.",
  "status": "PUBLISHED",
  "version": 2,
  "createdAt": "2026-08-01T12:00:00.000Z",
  "updatedAt": "2026-08-11T08:30:02.000Z"
}

Results sort by scheduled time and then ID. Supported query parameters:

Returns one event wrapped as { "data": Event }.

{
  "data": [/* events */],
  "meta": {
    "limit": 100,
    "nextCursor": "opaque-value-or-null"
  }
}

When nextCursor is present, send it unchanged with the same filters. Do not decode it or use it as permanent business data. Continue until it becomes null.

Open the authenticated Server-Sent Events endpoint to receive durable create, update, and delete messages. Each message includes an incrementing ID, operation, event ID, timestamp, and the new event payload (or its ID for deletions).

curl -N 'http://localhost:8080/api/v1/events/stream' \
  --header 'Authorization: Bearer es_test_your_key'

Reconnect with the last received SSE ID in Last-Event-ID, or pass it as?after=123. Without a cursor, the stream begins with future changes. Clients that cannot hold an SSE connection may still poll the list endpoint withupdatedSince.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request contains invalid fields",
    "details": {}
  }
}

Expect 400 for malformed requests, 401 for missing or invalid API keys, 403 for staff authorization, 404 for missing events, 409 for duplicates or stale edits, 413/415 for invalid uploads, 422 for field validation, 429 for an exhausted API-key daily limit, and 500 for an unexpected server/database failure.

Include the loaded event version in PATCH requests. A stale version returns 409 instead of overwriting another staff member’s changes.

Required headers are DATE, TIME, COUNTRY, CATEGORY, IMPORTANCE, EVENT NAME, and SUMMARY. Optional value fields include PREVIOUS, FORECAST, ACTUAL, and UNIT.

Workbook times use the configured ECONSTREAM_IMPORT_TIMEZONE. Use dryRun=true in the multipart form to validate without writing.