Deterministic series selection by facets

The series matching a facet selection - the same set every time, no text-match luck. Combine exact tags (tags=bis;france) with validated named facets: geo=, source=, frequency=, seasonality=, concept= (a value in the wrong facet is refused with the right one named). q= keeps a free-text constraint: the same q you faceted with on /api/v1/macro/facets, so counts seen there stay true here. exclude= removes tags; /api/v1/macro/facets shows what exists. Fetch any returned series from /api/v1/fred/series/{series_id}. TITLES ARE NOT UNIQUE - read units before choosing between identically titled series. Page with the returned next_offset, never your own arithmetic: later waves may annotate and filter rows, and next_offset is the upstream continuation point that stays correct.

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200OK

application/json

Matching series with units, frequency and popularity.

Bodyapplication/json

Example

{
    "data": {
        "total": 0,
        "returned": 0,
        "offset": 0,
        "next_offset": 0,
        "selected": [
            "string"
        ],
        "excluded": [
            "string"
        ],
        "q": "string",
        "series": [
            {
                "series_id": "string",
                "title": "string",
                "units": "string",
                "frequency": "string",
                "seasonal_adjustment": "string",
                "popularity": 0,
                "in_catalog": true
            }
        ],
        "source": "string",
        "fetched_at": "string"
    },
    "meta": {
        "endpoint": "/api/v1/fred/us/cpi",
        "data_time": "2026-04-16T14:30:00Z",
        "response_time": "2026-04-16T14:30:12Z",
        "provider": "Sugra API v1.0.1",
        "source": "string",
        "attribution": "string",
        "fallback_used": true,
        "fallback_chain": [
            "string"
        ],
        "cached": true,
        "stale": true
    }
}

🟠401Unauthorized

🟠422Parameter Error

🟠429

🔴503Service Unavailable