# QuantGist FAQ

## What is QuantGist?

QuantGist is a structured market intelligence API for economic calendar events, financial news, earnings, and market-moving data. It normalizes data from multiple sources into consistent API objects with UTC timestamps, impact labels, sentiment scoring, surprise scoring, symbol tagging, and plan-based access controls.

## Calendar vs Events — What's the Difference?

Use `/v1/calendar` for scheduled economic releases and upcoming market calendar workflows. Use `/v1/events` for the broader event feed, including news headlines, economic releases, earnings, IPOs, and other market-moving events.

Calendar answers: "What is scheduled?" Events answers: "What happened or was published?"

## Earnings vs Events — What's the Difference?

Use `/v1/earnings` when you need typed earnings fields such as EPS estimate, EPS actual, revenue estimate, revenue actual, fiscal period, report session, surprise percent, and per-field provenance. Use `/v1/events?event_type=earnings` only when earnings need to appear inside a broader unified event feed.

## When should I use Calendar?

Use Calendar for CPI, NFP, GDP, PMI, retail sales, unemployment claims, FOMC decisions, ECB meetings, central bank minutes, and other scheduled macro events.

## When should I use Events?

Use Events for market news feeds, alert bots, dashboards, broad monitoring, symbol-tagged event search, and unified timelines that combine scheduled releases with published headlines.

## When should I use Earnings?

Use Earnings for company reporting calendars, ticker earnings history, EPS and revenue surprise screens, confirmed vs projected report dates, and corporate-event research.

## When should I use webhooks?

Use webhooks when you need push delivery for alerts, bots, automation, or real-time workflows. Use polling for simple dashboards, research jobs, and periodic sync.

## What are the main API endpoints?

- `GET /v1/events`
- `GET /v1/events/historical`
- `GET /v1/calendar`
- `GET /v1/calendar/upcoming`
- `GET /v1/earnings`
- `GET /v1/earnings/upcoming`
- `GET /v1/earnings/{ticker}`
- `GET /v1/watchlists`
- `GET /v1/webhooks`
- `GET /v1/usage`

## What is the Free plan?

The Free plan includes 100 requests per day, 365 days of history, a 15-minute data delay, one watchlist, and no sentiment fields.

## Which plan has real-time data?

Pro, Team, and Enterprise have real-time access. Starter has a 1-minute delay. Free has a 15-minute delay.

## Which endpoint should an AI agent use?

AI agents should use `/v1/events` for broad retrieval, `/v1/calendar/upcoming` for near-term scheduled risk, `/v1/calendar` for date-window calendar questions, and `/v1/earnings` for company-specific earnings questions.

## Which endpoint should a trading bot use?

Trading bots should use `/v1/calendar/upcoming` or `/v1/calendar` for no-trade windows around high-impact scheduled events. They can use `/v1/events` for broader market monitoring and webhooks for push alerts.

## What is `impact`?

`impact` is a categorical market-importance label: `high`, `medium`, `low`, or `unknown`.

## What is `impact_score`?

`impact_score` is a numeric 0.0 to 1.0 estimate of expected market importance. It is useful for sorting, ranking, thresholds, and automation.

## What is `surprise_score`?

`surprise_score` measures how much an actual released value deviated from the forecast. It is useful after scheduled releases and earnings reports.

## What is `sentiment_score`?

`sentiment_score` is a -1.0 to 1.0 value that estimates the tone of an event or headline. It is available on Starter plans and above.

## Why are some fields null?

Fields can be null because the source did not provide the value, the event has not released yet, enrichment has not run yet, or the caller's plan does not include the field.

## Can I republish QuantGist data?

Raw data redistribution depends on plan and license terms. Free is for evaluation and non-commercial prototyping. Public redistribution or resale may require Enterprise terms.

## Where is the machine-readable documentation?

- LLM summary: `https://api.quantgist.com/llms.txt`
- Full LLM reference: `https://api.quantgist.com/llms-full.txt`
- AI assets catalog: `https://quantgist.com/ai-assets.md`
- OpenAPI schema: `https://api.quantgist.com/openapi.json`