Give your product a reliable view of what is scheduled, when it releases, how important it is, what the consensus expects, what came before, and — on Starter and above — what actually printed at release.
GET /v1/calendar 18 currencies covered Three impact levels Live actuals on Starter+ source=primary · Starter+ A useful calendar API has to stay queryable before the event, meaningful at the release moment, and predictable enough for production software to poll without custom cleanup logic.
Schedule, currency, impact, forecast, previous, actual, source and stable identifiers arrive through one predictable response shape.
Your application works against one model instead of stitching together a calendar UI, a release feed and a custom normalization layer.Upcoming events carry forecast and previous readings. Primary rows receive the released result at announcement time on Starter and above.
Use prev_hours to pull recently released events without inventing your own "what just changed?" cache.Every row exposes source. Primary and secondary streams can be queried separately, while the default combined view normalizes the overlap.
Advanced consumers can inspect the raw streams; most applications can simply use the combined view.Filter by currency, impact, date range, upcoming or recent hours, event-title search and source, with predictable pagination for wider windows.
Request only the events your product needs instead of downloading a giant calendar and filtering it in application code.High, Medium, Low impact classification so your system knows which events to prioritize.
Filter by currency (USD, EUR, GBP...), impact level, and date range. Get only the events that matter to your portfolio.
Consensus forecast, previous value, and actual result (once released) for every event.
UTC timestamps for every release. Know exactly when to widen stops, close positions, or prepare to enter.
Choose the workload and the request updates. The payload below is the response shape rather than a sample reading, but the parameters, the field names and the null behaviour follow the production endpoint exactly.
/v1/calendar?currencies=USD&impact=high&next_hours=24&offset=0&limit=100
{
"success": true,
"data": {
"events": [
{
"id": "<stable event id>",
"datetime": "<ISO 8601 UTC>",
"currency": "USD",
"event": "<event title>",
"impact": "high",
"forecast": "<consensus>",
"previous": "<prior period>",
"actual": null,
"source": "primary",
"series_id": "<per-indicator key>"
}
],
"count": 1,
"pagination": {
"offset": 0,
"limit": 100,
"total": 1,
"has_more": false
},
"range": {
"from": "<window start, naive UTC>",
"to": "<window end, naive UTC>"
}
}
}
// Response SHAPE. Field names and null behaviour mirror the production endpoint;
// no forecast, previous or actual reading is invented on this page. The API is designed around that lifecycle, so the same contract can power upcoming-event views, release monitoring and recent-event workflows.
The event enters the calendar with a UTC release time, a currency and an impact classification.
datetime · currency · impactForecast and previous readings are attached as they become available before the release.
forecast · previousUse the forward window plus currency and impact filters to identify what matters to your application.
next_hours=24&impact=highOn eligible plans the numeric actual populates on the primary stream at announcement time.
actual · source=primaryUse a look-back window to retrieve the releases that already printed, newest first.
prev_hours=48Each row carries both the human-readable event information and the identifiers needed for production polling, grouping and source-aware behaviour.
id identifies an individual event
row and should be treated as opaque. series_id groups repeated
releases of the same indicator on primary rows, which makes it the key to use for
continuity across releases.
datetime ISO 8601 UTC release timestamp.
currency Affected currency such as USD, EUR, GBP or JPY.
event Human-readable event title.
impact low, medium or high.
forecast Consensus expectation when available.
previous Prior-period reading.
actual Released value on eligible primary rows.
source primary or secondary, always present.
id Stable event identifier across polls.
series_id Stable per-indicator key on primary rows.
The calendar exposes enough source detail for advanced consumers without forcing every customer to build their own source-normalization layer.
The default combined view hides overlapping primary and secondary releases that land on the same page; developers who need source-specific behaviour can request either stream explicitly.
?source=primary or secondary The richer release stream, and the one used for live result monitoring.
actual values at releaseseries_id for release continuityAn additional schedule and expectations stream, exposed transparently.
actual remains nullseries_id is nullsource only when your polling logic needs explicit stream
control — primary plus secondary always totals the combined view.
Central-bank decisions, employment, inflation, and other market-moving releases across major economies.
Released actual values are published at announcement time on plans with live actuals — not on a fixed refresh cycle. Consensus forecasts and previous values are available as soon as an event is scheduled.
The endpoint is designed to slot into products, automation and analytics systems instead of living as a standalone website calendar.
Show the events that matter to the symbols or currencies already visible in your product.
See Market MonitorPoll the look-back window or the primary stream and notify downstream systems when a new actual arrives.
Read the calendar guideAdd scheduled-event context to agent prompts and tools so generated analysis knows what is imminent or just released.
SDK optionsAnnotate charts, reports and datasets with event times, impact levels and released figures.
Pair with market dataBuild "what is coming today" modules or automated event briefs without maintaining a separate calendar database.
Explore widgetsPair event times with spreads, quotes and candles to study what happened around a release in your own analytics layer.
See Spread AnalysisAutomatically adjust position sizing, close open trades, or trigger straddle strategies 30 minutes before high-impact releases.
# Close all USD positions before NFP
events = get_calendar(currencies="USD", impact="high")
for event in events:
if event["event"] == "Nonfarm Payrolls":
minutes_until = time_until(event["datetime"])
if minutes_until < 30:
close_all_usd_positions()Widen stop-losses or reduce leverage ahead of volatile releases. Your risk engine can query upcoming events and adjust parameters automatically.
// Reduce leverage before high-impact events
const events = await getCalendar({ next_hours: 24, impact: "high" });
if (events.length > 0) {
await setMaxLeverage(5); // Reduce from 20x to 5x
console.log("High-impact event today - leverage reduced");
}Compare actual vs forecast values when results are released. If actual CPI comes in higher than forecast, trigger buy on the affected currency. Calendar data makes this comparison trivial.
Build an upcoming-events widget for your trading dashboard. Filter by the currencies in your portfolio and show impact levels with color coding. The API does the heavy lifting.
Authenticate with X-API-Key, send filters as query parameters, and read
events from data.events.
curl -H "X-API-Key: YOUR_API_KEY" \
"https://tickatlas.com/v1/calendar?currencies=USD,EUR&impact=high&next_hours=72&offset=0&limit=100"import requests
resp = requests.get(
"https://tickatlas.com/v1/calendar",
headers={"X-API-Key": "YOUR_API_KEY"},
params={
"currencies": "USD,EUR",
"impact": "high",
"next_hours": 72
}
)
events = resp.json()["data"]["events"]
for event in events:
print(f"{event['datetime']}: {event['event']}")
print(f" Impact: {event['impact']}")
print(f" Forecast: {event['forecast']}")
print(f" Previous: {event['previous']}")const res = await fetch(
"https://tickatlas.com/v1/calendar" +
"?currencies=USD,EUR&impact=high&next_hours=72",
{ headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { data } = await res.json();
// Check for events in the next hour
const now = new Date();
const upcoming = data.events.filter(e => {
const eventTime = new Date(e.datetime);
const hoursUntil = (eventTime - now) / 3600000;
return hoursUntil > 0 && hoursUntil < 1;
});
if (upcoming.length > 0) {
console.log("HIGH IMPACT EVENT WITHIN 1 HOUR");
}The endpoint itself is paid. Released actuals are a second capability, available on Starter and above.
Pay-as-you-go can call the calendar, but actual stays null. Starter
adds the live released value. There is no free tier and
no trial — signing up puts you on pay-as-you-go with $2.50 of credit.
| Access | Calendar endpoint | Forecast / previous | Released actual |
|---|---|---|---|
| Pay as you go $2.50 of starting credit · 2 credits per calendar call | Yes | Yes | Null |
| Starter $29/month · 10,000 requests a day · 120/min | Yes | Yes | Yes |
| Pro $79/month · 100,000 requests a day · 600/min | Yes | Yes | Yes |
| Enterprise $349/month · 1,000,000 requests a day · 6000/min | Yes | Yes | Yes |
Legacy free and trial keys are not issued by signup and cannot reach this endpoint
at all — they receive 403 PLAN_UPGRADE_REQUIRED.
The product page explains the value. The documentation answers every implementation question without forcing the buyer to hunt around the site.
Parameters, response fields, source behaviour, polling strategies and code examples.
Read the guideConcise production reference for the calendar route, its plan gates and field behaviour.
Open referenceBrowse the OpenAPI surface and inspect request parameters interactively.
Open explorerOfficial Python, JavaScript/TypeScript, PHP and Go clients with retries and typed errors.
Choose an SDKThe answers below mirror the current calendar documentation rather than using generic marketing language.
All major currencies (USD, EUR, GBP, JPY, AUD, NZD, CAD, CHF) plus CNY, INR, BRL, and others. You can filter by one or multiple currencies using comma-separated values.
Up to 30 days ahead in a single request — either with next_hours (max 720 hours) or an explicit from/to range (max 30 days). The schedule typically carries several weeks of upcoming events, and forecast or previous values are present on roughly three quarters of them; the rest fill in as the release approaches. Requesting a range wider than 30 days returns a RANGE_TOO_LARGE error. A wide window usually holds more than one page — limit caps at 500 results, so follow pagination.has_more and use offset to read the far end of the window.
Yes — prev_hours opens a rolling look-back window of 1–96 hours over recently released events, and a pure look-back query comes back newest-first so the latest release sits on page one. Combine it with the forward window to straddle the current moment, as long as the combined span stays inside the 30-day range ceiling.
Released values appear at announcement time on Starter and above. Until an event releases — and on every tier below Starter — the actual field is null, while forecast and previous are available to everyone. Some events never carry a numeric actual at all: speeches, press conferences and rate statements have nothing to publish.
Both streams carry scheduling information. Primary rows are the only rows that can receive released actuals and they are the rows that carry a series_id. Secondary rows keep actual and series_id null. Most applications can use the default combined view; the source filter exists for advanced polling logic, and anything other than those two exact lowercase tokens is rejected with 400 INVALID_SOURCE.
Yes. Use q for a case-insensitive title search, with a maximum query length of 100 characters. Currency filtering accepts comma-separated codes, and country is an alias for currencies.
No. The endpoint is designed for upcoming schedules and recent release monitoring, and prev_hours is capped at 96 hours. If you need long-term event-history warehousing, persist the rows your own application consumes or talk to us about a custom requirement.
The calendar is a paid endpoint. Free and trial keys receive 403 PLAN_UPGRADE_REQUIRED and cannot call it. Pay-As-You-Go, Starter, Pro and Enterprise can. A second, separate gate controls the released actual value: only Starter and above receive it, so a PAYG caller consumes credits per call and still sees actual as null — if you need released values, Starter is the plan to be on rather than PAYG credits.
Keep the event contract clean, then combine it with price, spread and derived analytics in your own product logic.
Use one endpoint for scheduled economic events, expectations, release monitoring and source-aware event metadata. Start with the documentation, then choose pay-as-you-go for schedule access or Starter and above when released actuals matter.