---
title: "Search FRED series"
method: GET
path: "/api/v1/macro/search"
tags: ["Economics"]
---

# Search FRED series

`GET /api/v1/macro/search`

Full-text search across 800,000+ FRED economic series. Returns series metadata including series_id, title, frequency, units and popularity.

Fetch a result with GET /api/v1/fred/series/{series_id}, which accepts any series_id in the FRED catalogue. The /macro/{country}/{section} route is a different thing: it serves about 450 curated series and takes a section name, not a series_id, so it cannot fetch an arbitrary search result.

TITLES ARE NOT UNIQUE - read `units` before choosing. 'Real Residential Property Prices for France' is the title of BOTH QFRR628BIS (Index 2010=100, the price level) and QFRR368BIS (Percent per Annum, the growth rate). Picking by title alone returns the wrong one about half the time, and the response looks entirely valid either way. `popularity` is a reasonable tiebreak, not a guarantee.

## Query parameters

- `q` string, required — Free-text search query.
- `limit` integer — Maximum number of records to return.
- `offset` integer — Pagination offset (zero-indexed).
- `order_by` 'search_rank' | 'popularity' | 'title' | 'frequency' — Order-by field.

## Response `200`

FRED economic series matching the query, each with series_id, title, frequency, units, popularity and whether it is in the curated catalog. Fetch any of them by series_id from /api/v1/fred/series/{series_id}.

- EnvelopeMacroSearchData
  - `data` MacroSearchData, required
    - `query` string, required — Search query that produced these results.
    - `total` integer, required — Total count or sum.
    - `returned` integer, required — Number of records returned.
    - `offset` integer, required — Pagination offset applied to the result.
    - `series` MacroSeries[], required — Matching FRED series metadata.
      - `series_id` string, required — FRED series identifier.
      - `title` string, required — Display title.
      - `frequency` string, required — Observation frequency (daily, weekly, monthly, quarterly, annual).
      - `units` string, required — Units of measure.
      - `seasonal_adjustment` string, required — Seasonal adjustment label from FRED.
      - `popularity` integer, required — FRED popularity score.
      - `observation_start` string, required — First observation date.
      - `observation_end` string, required — Last observation date.
      - `last_updated` string, required — Last-update timestamp.
      - `in_catalog` boolean, required — Flag: series is in the Sugra macro catalog.
    - `source` string, required — Upstream data source identifier.
  - `meta` SugraMeta, required — Metadata attached to every /api/v1/* response envelope.
    - `endpoint` string, required — Requested endpoint path.
    - `data_time` string, required — ISO 8601 UTC timestamp of the source data, not of the request.
    - `response_time` string, required — ISO 8601 UTC timestamp when this response was produced.
    - `provider` string, required — API name and version.
    - `source` string, nullable — Identifier of the primary upstream source used for this response.
    - `attribution` string, nullable — Human-readable attribution mandated by an upstream source (e.g. a securities regulator or self-regulatory organization). Present only on responses whose source requires the owner and source to be clearly identified. Do not remove or alter it when using the response.
    - `fallback_used` boolean, nullable — True when the primary source failed and a fallback produced the data.
    - `fallback_chain` string[], nullable — Ordered list of sources attempted, in the order they were tried.
    - `cached` boolean, nullable — True when this response was served from the internal cache.
    - `stale` boolean, nullable — True when the cached response was returned after the upstream rate-limited or errored. Clients can use this to detect degraded data.

## Other responses

- `401` — Missing or invalid `x-api-key` header.
- `422` — Validation Error
- `429` — Daily rate limit exceeded. Check `X-RateLimit-Reset` for the next window.
- `503` — Upstream source is temporarily unavailable. Retry after a short delay.

---

[API](https://skmtc.net/sugra/apis/sugra-api.md) · [All operations](https://skmtc.net/sugra/apis/sugra-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sugra/sugra-api/versions/dcf7427e6897/schema)