TickAtlas
Calendar API Last updated: August 2026

Economic Calendar API

Access scheduled economic events — NFP, CPI, FOMC, interest rate decisions, and 100+ more — with impact ratings, forecasts, previous readings, and actuals published the moment they release.

Endpoint

endpoint 
GET https://tickatlas.com/v1/calendar

Requires X-API-Key header. Returns upcoming scheduled events with optional filtering.

Query Parameters

Parameter Type Default Description
from string today Start date, ISO 8601 or YYYY-MM-DD. Ignored when next_hours/prev_hours is set.
to string +7 days End date. Maximum 30-day range from from.
next_hours integer — Look-ahead window in hours for next_hours (1–720, i.e. up to 30 days). Overrides from/to.
A wide window spans several pages — follow pagination.has_more and use offset to read its far end.
prev_hours integer — Look-back window in hours (1–96) — returns recently released events with their actual values (Starter+). Overrides from/to; combine with next_hours to straddle now. Values above 96 return 422.
impact string all Filter by impact: low, medium, high, or omit for all.
currencies string — Comma-separated currency codes: USD,EUR,GBP
country string — Alias for currencies (same comma-separated codes).
q string — Search event titles, case-insensitive substring (max 100 chars).
offset integer 0 Number of results to skip for pagination.
limit integer 100 Max events to return (1-500).
source string both Restrict to one stream: primary or secondary (lowercase, single value, exact match). Omitted returns both streams, unchanged. secondary is the raw secondary stream: it can include a duplicate of a primary release that the default view hides when both fall on the same page, so pagination.total of primary plus secondary always equals the default total, while the default count can be lower by those hidden duplicates. Any other value — including an empty one — returns 400 INVALID_SOURCE.

Response Fields

Events are returned under data.events[]; data.count, data.range and data.pagination sit alongside them. Each event carries:

Field Description
idEvent identifier, stable across polls: 16 hexadecimal characters. Treat it as opaque; use series_id to link releases of the same indicator.
datetimeISO 8601 UTC timestamp of the event release (e.g., 2026-08-07T12:30:00+00:00)
currencyAffected currency (USD, EUR, GBP, JPY, etc.)
eventFull event name (e.g., "Non-Farm Payrolls")
impactEvent market impact: low, medium, or high
forecastAnalyst consensus forecast (string, may include units)
previousPrior period reading
actualThe released figure, populated the moment it prints — on primary rows only; a secondary row's actual stays null permanently. A Starter+ feature. Note there are two separate gates: free and trial keys cannot call this endpoint at all (403 PLAN_UPGRADE_REQUIRED); PAYG and Tool keys can call it but always receive null here; Starter and above see the released value, null only until the event prints. Use prev_hours to fetch recently released events with their actuals.
sourceprimary or secondary — always present, never null. The primary stream is the only one that ever receives an actual; the secondary stream carries schedule, forecast and previous only. Filter with ?source=.
series_idStable per-indicator key (string) on every primary row; null on every secondary row. Group releases by it to build a per-indicator history.

Example Response

200 OK 
{
  "success": true,
  "data": {
    "events": [
      {
        "id": "acb808eac77e0bbe",
        "datetime": "2026-09-08T23:50:00+00:00",
        "currency": "JPY",
        "event": "M2 Money Stock y/y",
        "impact": "low",
        "forecast": "2.2%",
        "previous": "2.2%",
        "actual": null,
        "source": "secondary",
        "series_id": null
      },
      {
        "id": "7c1e9a04b2f35d68",
        "datetime": "2026-09-08T23:50:04+00:00",
        "currency": "JPY",
        "event": "BoJ M2 Money Stock y/y",
        "impact": "low",
        "forecast": "2.0%",
        "previous": "2.2%",
        "actual": "2.0%",
        "source": "primary",
        "series_id": "3f8a21c07d9e5b46"
      }
    ],
    "count": 2,
    "range": {
      "from": "2026-09-08T13:45:00",
      "to": "2026-09-12T19:45:00"
    },
    "pagination": {
      "offset": 0,
      "limit": 100,
      "total": 2,
      "has_more": false
    }
  }
}

Code Examples

cURL

cURL 
# Upcoming — high-impact events in the next 24 hours
curl -X GET "https://tickatlas.com/v1/calendar?impact=high&next_hours=24&offset=0&limit=100" \
  -H "X-API-Key: YOUR_API_KEY"

# Just released — events from the last 48 hours WITH their actuals (max prev_hours=96)
curl -X GET "https://tickatlas.com/v1/calendar?prev_hours=48&impact=high&limit=100" \
  -H "X-API-Key: YOUR_API_KEY"

# Filter by currency
curl -X GET "https://tickatlas.com/v1/calendar?currencies=USD,EUR&next_hours=48&offset=0&limit=100" \
  -H "X-API-Key: YOUR_API_KEY"

# All events this week (168 hours)
curl -X GET "https://tickatlas.com/v1/calendar?next_hours=168&offset=0&limit=100" \
  -H "X-API-Key: YOUR_API_KEY"

Python

Python 
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://tickatlas.com/v1/calendar"

# Events are under data.events; pagination + range under data too.
def get_events(**params):
    r = requests.get(BASE_URL, headers={"X-API-Key": API_KEY}, params=params)
    return r.json()["data"]["events"]

# Upcoming: high-impact events in the next 24 hours
upcoming = get_events(impact="high", next_hours=24)
for e in upcoming:
    print(f"{e['datetime']} | {e['currency']} | {e['event']} | Impact: {e['impact']}")

# Just released: what came out in the last 48 hours, WITH actuals (Starter+).
# prev_hours is a rolling backward window (max 96h), newest-first.
released = get_events(prev_hours=48, impact="high")
for e in released:
    if e["actual"] is not None:
        print(f"{e['event']}: actual {e['actual']} vs forecast {e['forecast']}")

Common Use Cases

News Trading Bot

Poll the calendar before each new position entry. If a high-impact event's datetime is less than 30 minutes away (compute datetime − now), hold off on new trades until after the release.

Beat/Miss Momentum Signal

After datetime passes, poll until actual is non-null. Compare to forecast — a significant beat often triggers a momentum move in the affected currency.

Pre-Event Discord Alert

Run every 5 minutes. When a high-impact event's datetime is 30 minutes out or less, fire a Discord or Slack webhook to alert your team.

Related Resources