Economics

Deterministic series selection by facets

Changed on

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.

get/api/v1/macro/series

Request

  • Base URL: https://sugra.ai
  • URL: https://sugra.ai/api/v1/macro/series
  • Auth: API key in header x-api-key

Query parameters

tagsstring nullable

Exact tag tokens, semicolon- or comma-joined. Unknown tags reach FRED and come back as 400 naming the offender.

qstring nullable

Free-text constraint carried over from /macro/facets?q=... - keeps the selection inside that search.

excludestring nullable

Tags to exclude.

geostring nullable

Country/region facet value.

sourcestring nullable

Originator facet value.

frequencystring nullable

Frequency facet value.

seasonalitystring nullable

Seasonality facet value.

conceptstring nullable

Concept facet value(s), comma-joined.

measurestring nullable

Filter by measure: index, level, money, money_saar, rate_pct, spread_pct, count, growth_pct, share_pct, ratio, price. Every row carries measure regardless; rows dropped by this filter are counted in filtered_out_by_measure. ambiguous and unclassified are visible values a concrete filter excludes.

order'popularity' | 'series_id'

popularity: most-used first. series_id: stable alphabetical, best for full walks.

limitinteger

Series per page (upstream ceiling, measured).

offsetinteger

Upstream offset. Use the next_offset from the previous response.

Response

Matching series with units, frequency and popularity.

Example response

{
  "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",
    "data_age_days": 8.532,
    "source": "sugra_crypto",
    "attribution": "Short interest and Reg SHO daily short volume data is owned by and sourced from FINRA (Financial Industry Regulatory Authority).",
    "fallback_chain": [
      "sugra_crypto",
      "sugra_finance"
    ],
    "stale_since": "2026-09-08T12:00:00Z",
    "period": "2026-Q1",
    "notes": "the UKMTO report behind these counts is dated 2026-08-21 and is 11 days old"
  }
}

Changes

  • d2472ec2cf81Revision changes
    • breaking

      added subschema #2 to the response body oneOf list for the response status

    • breaking

      the response's body type changed from object to no type for status

    • breaking

      removed the required property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

  • 4f8853a61440Revision changes
    • info

      added the optional property / to the response with the status