Concepts
Foresight API normalizes provider-specific economic data into a small resource model.
Sources
A source is a data provider or derived-data publisher. Examples include public providers such as FRED, BLS, BEA, and BIS, plus Creative Foresight itself.
Source records include a stable slug, display name, provider metadata, category, documentation URL, and active indicator count.
Indicators
An indicator is a named time series such as UNRATE or cf:labor_composite. Indicator records include the source, category, subcategory, access_tier, unit, frequency, active state, default region, and available regions.
Some providers reuse codes. Use the source query parameter when a code is ambiguous.
Categories are taxonomy only. The top-level category is one of 13 fixed domains: macro, labor, prices, markets, housing, government-finance, demographics, business, energy, crypto, health, environment, or education. subcategory is a meaningful kebab-case second level within that domain.
Access is controlled by access_tier, not by category. free indicators are available to free-tier keys. premium indicators require an unrestricted key, a key granting creative-foresight, or x402 payment on payable endpoints.
Observations
Observations are dated values for an indicator and region. Observation rows include:
| Field | Meaning |
|---|---|
date | Observation date. |
value | Numeric value, or null when the source publishes a gap. |
indicator | Indicator code returned by the query. |
region | Region code for the row. |
unit | Unit label, such as percent. |
source | Source slug for the row. |
source_updated_at | Provider update timestamp when available. |
is_preliminary | Whether the source marks the value as preliminary. |
revision | Revision number for the period. |
Regions
Regions identify geography. National series commonly use US. County and subnational series use FIPS-style codes where applicable.
GET /v1/regions can filter by type and parent, which lets clients discover available counties for a state or local regions under a parent geography.
Revisions and preliminary values
By default, observation queries return the latest revision for each period. Use include_revisions=true when you need revision history.
Preliminary source releases are marked with is_preliminary. Treat preliminary values as live release data rather than final historical truth.
The cf:* derived layer
Creative Foresight original indicators use cf:* codes and access_tier: "premium". These are derived series no provider publishes directly.
Every derived value traces back to the public series behind it, and those series stay queryable through the same API — so agents and applications get a stable signal whose underlying data chain stays auditable.
The full catalog — what each series measures, its inputs, and cadence — is on Derived Indicators.