> ## Documentation Index
> Fetch the complete documentation index at: https://fred-mcp-server.amorelli.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# fred_search

> Search for FRED economic data series by keywords, tags, or filters

# fred\_search

Search across all 800,000+ FRED series using powerful text search, tag filtering, and attribute filters.

## Overview

The `fred_search` tool enables sophisticated searching across FRED's vast database. Use it to:

* Find series by keywords in titles and descriptions
* Filter by tags like "gdp", "monthly", "seasonally adjusted"
* Combine multiple search criteria
* Filter by frequency, units, or seasonal adjustment
* Sort by relevance, popularity, or recency

## Parameters

<ParamField path="search_text" type="string">
  Text to search for in series titles and descriptions.

  **Search tips:**

  * Use specific terms like "unemployment rate" or "consumer price index"
  * Searches are case-insensitive
  * Multiple words are searched as phrases
  * Partial matches are included
</ParamField>

<ParamField path="search_type" type="string" default="full_text">
  Type of search to perform.

  **Options:**

  * `full_text`: Search titles and descriptions
  * `series_id`: Search by exact series ID match
</ParamField>

<ParamField path="tag_names" type="string">
  Comma-separated list of tags to filter by. All specified tags must be present.

  **Common tags:**

  * Geographic: `usa`, `state`, `county`, `msa`
  * Frequency: `daily`, `weekly`, `monthly`, `quarterly`, `annual`
  * Adjustment: `sa` (seasonally adjusted), `nsa` (not seasonally adjusted)
  * Topic: `gdp`, `inflation`, `employment`, `housing`, `interest rate`

  **Example:** `"monthly,sa,employment"`
</ParamField>

<ParamField path="exclude_tag_names" type="string">
  Comma-separated list of tags to exclude. Series with these tags will be filtered out.

  **Example:** `"discontinued,projection"`
</ParamField>

<ParamField path="limit" type="number" default="25">
  Maximum number of results to return (1-1000).
</ParamField>

<ParamField path="offset" type="number" default="0">
  Number of results to skip for pagination.
</ParamField>

<ParamField path="order_by" type="string" default="search_rank">
  Field to order results by.

  **Options:**

  * `search_rank`: Relevance to search terms
  * `series_id`: Alphabetical by ID
  * `title`: Alphabetical by title
  * `popularity`: Most accessed series first
  * `last_updated`: Most recently updated
  * `observation_start`: Earliest data first
  * `observation_end`: Latest data first
  * `frequency`: Grouped by frequency
  * `units`: Grouped by units
</ParamField>

<ParamField path="sort_order" type="string" default="desc">
  Sort order for results.

  **Options:**

  * `asc`: Ascending order
  * `desc`: Descending order
</ParamField>

<ParamField path="filter_variable" type="string">
  Variable to filter by.

  **Options:**

  * `frequency`: Filter by data frequency
  * `units`: Filter by measurement units
  * `seasonal_adjustment`: Filter by adjustment type
</ParamField>

<ParamField path="filter_value" type="string">
  Value to filter the variable by. Must be used with `filter_variable`.

  **Frequency values:**

  * `d`: Daily
  * `w`: Weekly
  * `m`: Monthly
  * `q`: Quarterly
  * `a`: Annual

  **Units values:**

  * `lin`: Levels
  * `pch`: Percent change
  * `pc1`: Percent change from year ago
  * `index`: Index values

  **Seasonal adjustment values:**

  * `sa`: Seasonally adjusted
  * `nsa`: Not seasonally adjusted
</ParamField>

## Examples

### Basic Keyword Search

<CodeGroup>
  ```json Request theme={null}
  {
    "tool": "fred_search",
    "params": {
      "search_text": "unemployment rate",
      "limit": 5
    }
  }
  ```

  ```json Response theme={null}
  {
    "series": [
      {
        "id": "UNRATE",
        "title": "Unemployment Rate",
        "observation_start": "1948-01-01",
        "observation_end": "2024-12-01",
        "frequency": "Monthly",
        "units": "Percent",
        "seasonal_adjustment": "Seasonally Adjusted",
        "popularity": 98,
        "tags": ["usa", "monthly", "sa", "labor", "unemployment"]
      },
      {
        "id": "U6RATE",
        "title": "Total Unemployed, Plus All Marginally Attached Workers",
        "observation_start": "1994-01-01",
        "observation_end": "2024-12-01",
        "frequency": "Monthly",
        "units": "Percent",
        "seasonal_adjustment": "Seasonally Adjusted",
        "popularity": 85,
        "tags": ["usa", "monthly", "sa", "labor", "u6"]
      }
    ],
    "metadata": {
      "count": 5,
      "total": 1247
    }
  }
  ```
</CodeGroup>

### Search with Tag Filtering

<CodeGroup>
  ```json Request theme={null}
  {
    "tool": "fred_search",
    "params": {
      "search_text": "inflation",
      "tag_names": "usa,monthly,sa",
      "limit": 3
    }
  }
  ```

  ```json Response theme={null}
  {
    "series": [
      {
        "id": "CPIAUCSL",
        "title": "Consumer Price Index for All Urban Consumers: All Items",
        "frequency": "Monthly",
        "units": "Index 1982-1984=100",
        "seasonal_adjustment": "Seasonally Adjusted",
        "tags": ["usa", "monthly", "sa", "cpi", "inflation", "price"]
      },
      {
        "id": "CPILFESL",
        "title": "Consumer Price Index: All Items Less Food and Energy",
        "frequency": "Monthly",
        "units": "Index 1982-1984=100",
        "seasonal_adjustment": "Seasonally Adjusted",
        "tags": ["usa", "monthly", "sa", "core cpi", "inflation"]
      },
      {
        "id": "PCEPI",
        "title": "Personal Consumption Expenditures: Chain-type Price Index",
        "frequency": "Monthly",
        "units": "Index 2017=100",
        "seasonal_adjustment": "Seasonally Adjusted",
        "tags": ["usa", "monthly", "sa", "pce", "inflation"]
      }
    ]
  }
  ```
</CodeGroup>

### Filter by Frequency

<CodeGroup>
  ```json Request theme={null}
  {
    "tool": "fred_search",
    "params": {
      "search_text": "gdp",
      "filter_variable": "frequency",
      "filter_value": "q",
      "order_by": "popularity",
      "limit": 5
    }
  }
  ```

  ```json Response theme={null}
  {
    "series": [
      {
        "id": "GDP",
        "title": "Gross Domestic Product",
        "frequency": "Quarterly",
        "units": "Billions of Dollars",
        "seasonal_adjustment": "Seasonally Adjusted Annual Rate"
      },
      {
        "id": "GDPC1",
        "title": "Real Gross Domestic Product",
        "frequency": "Quarterly",
        "units": "Billions of Chained 2017 Dollars",
        "seasonal_adjustment": "Seasonally Adjusted Annual Rate"
      }
    ]
  }
  ```
</CodeGroup>

### Search by Series ID

<CodeGroup>
  ```json Request theme={null}
  {
    "tool": "fred_search",
    "params": {
      "search_text": "DGS10",
      "search_type": "series_id"
    }
  }
  ```

  ```json Response theme={null}
  {
    "series": [
      {
        "id": "DGS10",
        "title": "Market Yield on U.S. Treasury Securities at 10-Year Constant Maturity",
        "frequency": "Daily",
        "units": "Percent",
        "observation_start": "1962-01-02",
        "observation_end": "2024-12-31"
      }
    ]
  }
  ```
</CodeGroup>

### Exclude Discontinued Series

<CodeGroup>
  ```json Request theme={null}
  {
    "tool": "fred_search",
    "params": {
      "search_text": "federal funds",
      "exclude_tag_names": "discontinued",
      "limit": 5
    }
  }
  ```

  ```json Response theme={null}
  {
    "series": [
      {
        "id": "DFF",
        "title": "Federal Funds Effective Rate",
        "frequency": "Daily",
        "status": "Active"
      },
      {
        "id": "FEDFUNDS",
        "title": "Federal Funds Effective Rate",
        "frequency": "Monthly",
        "status": "Active"
      }
    ]
  }
  ```
</CodeGroup>

## Search Strategies

### Finding Economic Indicators

<Tabs>
  <Tab title="GDP & Growth">
    ```json theme={null}
    {
      "search_text": "gross domestic product",
      "tag_names": "usa,gdp",
      "filter_variable": "frequency",
      "filter_value": "q"
    }
    ```

    **Key Series:**

    * GDP: Nominal GDP
    * GDPC1: Real GDP
    * GDPPOT: Potential GDP
    * NYGDPMKTPCDWLD: World GDP Per Capita
  </Tab>

  <Tab title="Inflation">
    ```json theme={null}
    {
      "search_text": "consumer price",
      "tag_names": "usa,monthly,inflation",
      "order_by": "popularity"
    }
    ```

    **Key Series:**

    * CPIAUCSL: CPI All Items
    * CPILFESL: Core CPI
    * PCEPI: PCE Price Index
    * DFEDTARU: Fed Target Rate
  </Tab>

  <Tab title="Employment">
    ```json theme={null}
    {
      "search_text": "employment",
      "tag_names": "usa,monthly,sa",
      "exclude_tag_names": "discontinued"
    }
    ```

    **Key Series:**

    * PAYEMS: Nonfarm Payrolls
    * UNRATE: Unemployment Rate
    * CIVPART: Labor Force Participation
    * EMRATIO: Employment-Population Ratio
  </Tab>

  <Tab title="Housing">
    ```json theme={null}
    {
      "search_text": "housing",
      "tag_names": "usa,monthly",
      "filter_variable": "seasonal_adjustment",
      "filter_value": "sa"
    }
    ```

    **Key Series:**

    * HOUST: Housing Starts
    * PERMIT: Building Permits
    * CSUSHPISA: Case-Shiller Index
    * MORTGAGE30US: 30-Year Mortgage Rate
  </Tab>
</Tabs>

### Regional Data Search

```json theme={null}
// State-level unemployment
{
  "search_text": "unemployment rate",
  "tag_names": "state,monthly",
  "limit": 50
}

// Metropolitan area GDP
{
  "search_text": "gdp",
  "tag_names": "msa,annual",
  "order_by": "title"
}

// County-level income
{
  "search_text": "personal income",
  "tag_names": "county,annual"
}
```

### International Data Search

```json theme={null}
// Global inflation rates
{
  "search_text": "inflation",
  "tag_names": "international,monthly",
  "exclude_tag_names": "usa"
}

// Exchange rates
{
  "search_text": "exchange rate",
  "tag_names": "daily,currency"
}

// International GDP comparison
{
  "search_text": "gdp growth",
  "tag_names": "international,annual,oecd"
}
```

## Common Tag Combinations

### By Geography

| Scope         | Tags            | Example Series         |
| ------------- | --------------- | ---------------------- |
| National      | `usa`           | UNRATE, GDP, CPIAUCSL  |
| State         | `state`         | CAUNRATE, CASTPRHHRSA  |
| Metro         | `msa`           | ATXURN, DALPRHHRSA     |
| County        | `county`        | PCPI01001, CAUNTY01001 |
| International | `international` | LRHUTTTTJPM156S        |

### By Frequency

| Frequency | Tag         | Common Uses                    |
| --------- | ----------- | ------------------------------ |
| Daily     | `daily`     | Interest rates, exchange rates |
| Weekly    | `weekly`    | Initial jobless claims         |
| Monthly   | `monthly`   | CPI, employment, retail sales  |
| Quarterly | `quarterly` | GDP, corporate profits         |
| Annual    | `annual`    | Population, long-term trends   |

### By Topic

| Topic             | Common Tags                       | Key Series          |
| ----------------- | --------------------------------- | ------------------- |
| Monetary Policy   | `fed, interest rate, monetary`    | DFF, DFEDTARU       |
| Inflation         | `inflation, cpi, price`           | CPIAUCSL, PCEPI     |
| Labor Market      | `employment, labor, unemployment` | UNRATE, PAYEMS      |
| Financial Markets | `stock, bond, yield`              | SP500, DGS10        |
| Housing           | `housing, real estate, mortgage`  | HOUST, MORTGAGE30US |

## Advanced Search Patterns

### Complex Queries

```json theme={null}
// Find all seasonally adjusted monthly employment data for California
{
  "search_text": "employment",
  "tag_names": "california,monthly,sa",
  "filter_variable": "units",
  "filter_value": "lin",
  "order_by": "popularity"
}

// Get high-frequency financial indicators
{
  "search_text": "financial",
  "tag_names": "daily",
  "exclude_tag_names": "discontinued,forecast",
  "order_by": "last_updated",
  "limit": 20
}

// Find recession indicators
{
  "search_text": "recession",
  "tag_names": "usa,monthly",
  "order_by": "popularity",
  "limit": 10
}
```

### Pagination for Large Results

```json theme={null}
// First page
{
  "search_text": "interest rate",
  "limit": 100,
  "offset": 0
}

// Second page
{
  "search_text": "interest rate",
  "limit": 100,
  "offset": 100
}

// Third page
{
  "search_text": "interest rate",
  "limit": 100,
  "offset": 200
}
```

## Error Handling

### Common Errors

| Error                   | Cause                            | Solution                                  |
| ----------------------- | -------------------------------- | ----------------------------------------- |
| `No results found`      | Search too specific              | Broaden search terms or remove filters    |
| `Invalid tag_names`     | Malformed tag list               | Use comma-separated values without spaces |
| `Invalid filter_value`  | Wrong value for filter\_variable | Check valid values for the filter type    |
| `Limit exceeds maximum` | limit > 1000                     | Use limit ≤ 1000 and pagination           |

## Best Practices

<Steps>
  <Step title="Start Broad">
    Begin with general terms and progressively add filters
  </Step>

  <Step title="Use Tags Effectively">
    Combine geographic, frequency, and topic tags for precision
  </Step>

  <Step title="Sort by Popularity">
    Popular series are often the most reliable and widely used
  </Step>

  <Step title="Exclude Discontinued">
    Add `exclude_tag_names: "discontinued"` for active series only
  </Step>

  <Step title="Check Metadata">
    Review frequency, units, and seasonal adjustment before using data
  </Step>
</Steps>

## Related Tools

<CardGroup cols={2}>
  <Card title="fred_browse" icon="folder-tree" href="/api-reference/fred-browse">
    Browse categories systematically
  </Card>

  <Card title="fred_get_series" icon="chart-line" href="/api-reference/fred-get-series">
    Retrieve data for found series
  </Card>
</CardGroup>