The FRED series/observations endpoint returns the observations, or data values, for one economic data series (c01). The practical task for a reader who wants to recompute a chart is not 'fetch the data' but 'fetch the data the same way twice'. Most mismatch between two analysts comes from default parameters, not from the series itself. This guide walks the request parameters, the defaults, and the transformation codes, so a replication is auditable.
Start from the response format, because the default is not JSON
The endpoint can return XML, JSON, an Excel spreadsheet, or a zipped CSV, selected by setting the file_type parameter to xml, json, xlsx, or csv (c02). The default value of file_type is xml (c03). A reader who omits it and then parses the payload as JSON will fail for a reason unrelated to the data. Pin the format explicitly in every saved request.
The API key is a 32 character alpha-numeric lowercase string and is required (c05). The documentation shows the key abcdefghijklmnopqrstuvwxyz123456 as a demonstration value only (c04), so it must not be treated as a working credential. file_type is described as a key or file extension that indicates the type of file to send (c06).
Pin the time window and the row count
Two date parameters bound the window. The start date is a YYYY-MM-DD formatted string, optional, with default 1776-07-04, the earliest available (c11). The end date is a YYYY-MM-DD formatted string, optional, with default 9999-12-31, the latest available (c12). Because the defaults span everything, an unpinned request returns a different row count as the series grows; two runs on different days are not comparable unless both dates are written into the request.
A separate optional date, a YYYY-MM-DD formatted string with default today's date (c08), also exists. Vintage information is documented separately: the source points to Real-Time Periods and vintage_dates for more information (c07). Treat vintage handling as an open item unless you have read that separate documentation, because it governs which version of a value you receive.
The limit parameter is an integer between 1 and 100000, optional, default 100000 (c09). This is a row cap, not a date filter. If a series plus its window exceeds the cap, the truncation happens at the cap, so a replication should record the limit alongside the dates. Sorting is ascending or descending observation_date order (c10); the stored order does not change the values, but it changes how a truncated result is cut.
Frequency aggregation changes the unit of the row
Frequency is an optional parameter that indicates a lower frequency to aggregate values to (c15). The aggregation feature converts higher frequency data series into lower frequency data series, for example converting a monthly data series into an annual data series (c16, c17). The documented range is daily as the highest frequency and annual as the lowest (c18).
This matters for unit honesty. A monthly series aggregated to annual is no longer a monthly observation; each row is a derived annual value, and the label must say so. A chart that mixes an aggregated series with an unaggregated one is comparing different constructs.
The transformation code is part of the definition
The transformation parameter is a string, optional, default lin, meaning no transformation (c13). The accepted values and their meanings are listed in the source (c14). Because the default is levels, a reader who expects percent change but does not set the code will silently receive levels. The code belongs in the request record, next to the series ID and the dates.
| Code | Meaning (per source) |
|---|---|
| lin | Levels (No transformation) |
| chg | Change |
| ch1 | Change from Year Ago |
| pch | Percent Change |
| pc1 | Percent Change from Year Ago |
| pca | Compounded Annual Rate of Change |
| cch | Continuously Compounded Rate of Change |
| cca | Continuously Compounded Annual Rate of Change |
| log | Natural Log |
A worked example of why this matters: suppose a series has a value of 100 in one period and 110 in the next. Hypothetical: the lin series shows 110; the chg series shows 10; and the pch series shows 10 percent. The same underlying data yields three different numbers depending on the code. A reader comparing a 'change' chart against a 'levels' chart is comparing different transformations, not a data error.
What the source does not say
- The source does not state a specific HTTP status code or error payload for an invalid key or malformed date.
- The source does not state how the limit interacts with sorting to decide which rows are dropped, beyond the cap and order definitions.
- The source does not define the aggregation method (for example averaging versus summing) used for the frequency parameter.
- The source does not give a numeric example for any transformation code beyond the names and descriptions (c14).
- The source does not say whether the demonstration key (c04) returns any data at all.
The replication record
A reproducible request is a small set of pinned fields, and each field should be written down rather than left to a default. The checklist below is the multi-step verification task this endpoint implies; it is not a claim that any particular request has been run.
- Record the series identifier and the required 32 character lowercase key handling (c05).
- Pin file_type explicitly; remember the default is xml (c02, c03).
- Pin observation_start and observation_end; the defaults are 1776-07-04 and 9999-12-31 (c11, c12).
- Record the limit used; it is capped at 100000 with a default of 100000 (c09).
- Record the sort order, ascending or descending (c10).
- Record the frequency if you aggregate, and note the daily-to-annual range (c15, c16, c17, c18).
- Record the transformation code; the default is lin (c13, c14).
- Record the vintage handling or flag it as unresolved (c07).
The deliverable is a request line plus a note on units. If the note says 'levels, monthly, 2020-01-01 to 2024-01-01, ascending, limit 100000', a second analyst can rebuild the same numbers without guessing which default was silently applied.