FRED Getting Started: API Key, First Request (2026)

Getting started overview

Integrating with the FRED API primarily involves obtaining an API key and constructing URL-based requests to retrieve economic data. FRED, maintained by the Federal Reserve Bank of St. Louis, provides access to a database of more than 820,000 U.S. and international economic time series from the FRED API documentation. This guide outlines the steps to register for an API key, make your initial data retrieval request, and explore common subsequent actions.

The FRED API offers multiple endpoints to access categories, series, releases, and vintage data. All requests are made via HTTPS GET and require an API key for authentication. Responses are typically available in XML, JSON, or CSV formats, allowing developers flexibility in data processing. Understanding the structure of these requests and responses is fundamental to effective API utilization.

Quick Reference Steps

The following table provides a high-level overview of the initial setup process:

Create an account and get keys

Access to the FRED API requires a unique API key, which is obtained after registering for a free user account on the Federal Reserve Bank of St. Louis website. This key identifies your application and is necessary for all API calls.

Account Registration

1. Navigate to the FRED Registration Page: Open your web browser and go to the FRED User Registration form.
2. Complete the Form: Provide the required information, including your email address, desired username, and a strong password. You may also be asked for your institution or area of interest, which helps the St. Louis Fed understand the user base.
3. Verify Email: After submitting the form, a verification email will be sent to the address you provided. Follow the instructions in this email to activate your account. This step is crucial for confirming your identity and completing the registration process.
4. Log In: Once your email is verified, log in to your newly created FRED account using your username and password.

Requesting an API Key

After successfully logging into your FRED account, you can request an API key:

1. Access API Key Page: From your account dashboard, locate the section for API keys. This is usually found under a menu item like "My Account" or "API Keys". Alternatively, you can directly visit the FRED API documentation page which contains a link to request a key once logged in.
2. Request New Key: Click the button or link to "Request an API Key." You may be asked to agree to terms of service related to data usage, distribution, and attribution. Ensure you read these terms carefully, as they govern your use of FRED data from FRED's legal information.
3. Receive Your Key: Your unique API key will be generated and displayed on the screen. It is a long alphanumeric string. Copy and store this key securely. It is recommended to treat your API key like a password, as unauthorized access could lead to misuse of your API quota or other issues.

The FRED API key is typically a 32-character hexadecimal string. For example, a key might look like abcdef0123456789abcdef0123456789 (this is an example, not a real key). This key will be passed as a query parameter in every API request.

Your first request

Once you have your API key, you can make your first request to the FRED API. This example demonstrates how to retrieve the most recent value for the Gross Domestic Product (GDP) economic series, identified by the series ID "GDP". The base URL for the FRED API is https://api.stlouisfed.org/fred/.

API Endpoint for Series Observation

To get observations for a specific series, you will use the series/observations endpoint. The minimum required parameters are series_id and api_key. You can also specify the file_type for the response format (e.g., json, xml, csv).

Example request structure:

GET https://api.stlouisfed.org/fred/series/observations?series_id=GDP&api_key=YOUR_API_KEY&file_type=json

Replace YOUR_API_KEY with the actual API key you obtained.

Using cURL (Command Line)

cURL is a command-line tool for making network requests. It's a quick way to test your API key and endpoint.

curl "https://api.stlouisfed.org/fred/series/observations?series_id=GDP&api_key=YOUR_API_KEY&file_type=json"

Upon execution, this command will print the JSON response directly to your terminal. The response will contain metadata about the series and an array of observations, including dates and values.

Example (partial) JSON response:

{
  "realtime_start": "2026-05-29",
  "realtime_end": "2026-05-29",
  "observation_start": "1947-01-01",
  "observation_end": "2026-05-29",
  "units": "Billions of Dollars",
  "observations": [
    // ... previous observations ...
    {
      "date": "2023-01-01",
      "value": "26957.558"
    },
    {
      "date": "2023-04-01",
      "value": "27610.126"
    }
  ]
}

Using Python (with requests library)

Python is a common language for scripting API interactions. Install the requests library if you haven't already (pip install requests).

import requests
import json

api_key = "YOUR_API_KEY"  # Replace with your actual API key
series_id = "GDP"
file_type = "json"

url = f"https://api.stlouisfed.org/fred/series/observations?series_id={series_id}&api_key={api_key}&file_type={file_type}"

response = requests.get(url)

if response.status_code == 200:
    data = response.json()
    print(json.dumps(data, indent=2))
    # You can now process 'data'
    # For example, print the latest observation:
    if data and 'observations' in data and data['observations']:
        latest_observation = data['observations'][-1]
        print(f"Latest GDP: {latest_observation['value']} on {latest_observation['date']}")
else:
    print(f"Error: {response.status_code} - {response.text}")

This Python script makes the same request, retrieves the JSON response, and then prints it in a human-readable format, demonstrating how to parse the data programmatically.

Using R (with httr library)

R is widely used for statistical computing and graphics. Install the httr and jsonlite libraries if you haven't already (install.packages("httr"), install.packages("jsonlite")).

library(httr)
library(jsonlite)

api_key <- "YOUR_API_KEY" # Replace with your actual API key
series_id <- "GDP"
file_type <- "json"

url <- paste0("https://api.stlouisfed.org/fred/series/observations?series_id=", series_id, "&api_key=", api_key, "&file_type=", file_type)

response <- GET(url)

if (http_status(response)$category == "Success") {
  content_text <- content(response, "text", encoding = "UTF-8")
  data <- fromJSON(content_text)
  print(jsonlite::toJSON(data, pretty = TRUE))
  
  # Print the latest observation
  if (length(data$observations) > 0) {
    latest_observation <- tail(data$observations, 1)
    cat(paste0("Latest GDP: ", latest_observation$value, " on ", latest_observation$date, "\n"))
  }
} else {
  cat(paste0("Error: ", http_status(response)$status_code, " - ", content(response, "text"), "\n"))
}

This R script performs the API call, parses the JSON, and outputs the latest GDP observation, similar to the Python example.

Common next steps

After successfully retrieving your first data series, consider these common next steps to expand your use of the FRED API:

• Explore Other Endpoints: The FRED API offers various endpoints beyond series/observations. You can retrieve categories (fred/category), releases (fred/releases), or search for series (fred/series/search) as explained in the FRED API documentation. Each endpoint provides access to different facets of the FRED database.
• Filter and Manipulate Data: Experiment with additional query parameters to filter data. For example, you can specify observation_start and observation_end dates, change the frequency (e.g., frequency=q for quarterly), or apply transformations (e.g., units=pc for percent change from year ago). A comprehensive list of parameters for series observations is available in the FRED series observations documentation.
• Utilize FRED SDKs: For Python and R users, official and community-maintained SDKs can simplify API interactions by abstracting HTTP requests and JSON parsing. The fredapi Python library on PyPI and the Rblpapi R package for Bloomberg connectivity (though not direct FRED API, it shows API integration patterns) demonstrate how SDKs can streamline development.
• Handle Data Volume: For large datasets, consider pagination parameters such as limit and offset to retrieve data in manageable chunks. Be mindful of the API rate limits, which are typically 2,000 requests per day for an individual API key according to FRED API key details.
• Error Handling: Implement robust error handling in your application. The FRED API returns standard HTTP status codes (e.g., 400 for bad request, 403 for forbidden due to invalid API key). Parsing the error messages in the response body can help diagnose issues.
• Data Storage and Analysis: Decide how you will store and analyze the retrieved data. Options include databases, flat files, or direct integration into analytical tools. For example, using a SQL database for historical data management can improve query performance and data integrity for long-term projects.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips for the FRED API:

• Invalid API Key (HTTP 403 Forbidden): This is the most frequent issue.
• Check for Typos: Ensure your API key is copied exactly as provided, with no extra spaces or missing characters.
• Key Status: Verify that your API key is active. Log into your FRED account and check the status of your API key. If it was recently generated, it might take a few minutes to become fully active.
• Parameter Name: Ensure the parameter name is precisely api_key, not apiKey or APIKey. The FRED API is case-sensitive for parameter names.
• Invalid Series ID (HTTP 400 Bad Request):
• Verify Series ID: Double-check the series_id. Common series IDs like "GDP", "CPIAUCSL", or "UNRATE" are usually correct, but custom or less common series can have specific identifiers. You can search for series IDs directly on the FRED website or use the fred/series/search API endpoint as described in the FRED search documentation.
• Parameter Name: Ensure the parameter name is series_id.
• Incorrect Endpoint URL:
• Base URL: Confirm you are using https://api.stlouisfed.org/fred/ as the base URL.
• Endpoint Path: Ensure the endpoint path is correct, e.g., series/observations.
• HTTPS: All FRED API requests must use HTTPS. Plain HTTP requests will fail.
• Missing Required Parameters (HTTP 400 Bad Request):
• For the series/observations endpoint, both series_id and api_key are mandatory. Other endpoints may have different mandatory parameters. Refer to the specific FRED endpoint documentation for details.
• Rate Limiting (HTTP 429 Too Many Requests):
• If you make too many requests within a short period, the API might temporarily block your access. Wait a few minutes and try again. The default limit is 2,000 requests per day per API key. Implement delays or caching in your application to stay within these limits as recommended by Cloudflare's API rate limit practices.
• Network Issues:
• Verify your internet connection. Proxy settings or firewalls in your environment might be blocking outgoing requests to the FRED API domain.
• Response Format Issues:
• If the response is not parsed correctly, check the file_type parameter (e.g., file_type=json). Ensure your parsing code correctly handles the specified format.

When troubleshooting, always examine the HTTP status code and the response body for specific error messages, as these often provide direct clues about the problem.