Quickstart

From zero to a live JSON response in about two minutes. You need an API key, an HTTP client and nothing else - no SDK is required.

1. Get an API key

A key is generated for you on registration. Copy it from the Developer / Keys page.

The Free plan allows 50 requests per day across all endpoints. Every endpoint is available on every plan; paid plans only raise the daily volume.

2. Make your first request

Pass the key in the x-api-key header on every /api/ request. The example below pulls the latest three observations of the US Consumer Price Index (FRED series CPIAUCSL).

curl

Python (requests)

JavaScript (fetch)

3. Read the response

Every data endpoint returns the same envelope: your result under data, request metadata under meta. The response above:

{
  "data": {
    "series_id": "CPIAUCSL",
    "title": "Consumer Price Index for All Urban Consumers: All Items in U.S. City Average",
    "units": "Index 1982-1984=100",
    "units_short": "Index 1982-1984=100",
    "frequency": "Monthly",
    "seasonal_adjustment": "Seasonally Adjusted",
    "last_updated": "2026-07-14 08:10:40-05",
    "observation_start": "1600-01-01",
    "observation_end": "9999-12-31",
    "count": 3,
    "observations": [
      {"date": "2026-06-01", "value": 332.568},
      {"date": "2026-05-01", "value": 333.979},
      {"date": "2026-04-01", "value": 332.407}
    ]
  },
  "meta": {
    "endpoint": "/api/v1/fred/series/CPIAUCSL",
    "data_time": "2026-07-18T18:46:43Z",
    "response_time": "2026-07-18T18:46:43Z",
    "provider": "Sugra API v1.0.1",
    "source": "fred",
    "cached": true
  }
}

data - the payload; its shape is endpoint-specific and documented in the API Reference.

meta.source - the upstream source identifier.

meta.data_time / meta.response_time - when the data was produced and when the response was served.

meta.cached - whether the response came from the server-side cache.

4. Watch your rate-limit headers

Every response reports your daily budget (add -i to any curl call to see the headers):

X-RateLimit-Limit: 50
X-RateLimit-Remaining: 49
X-RateLimit-Reset: 2026-07-18T23:59:59Z

X-RateLimit-Limit - your plan's daily request allowance (50 shown for the Free plan).

X-RateLimit-Remaining - requests left today.

X-RateLimit-Reset - UTC timestamp when the counter resets; all counters reset at UTC midnight.

When the budget is exhausted the API returns 429 with a Retry-After header giving the whole seconds until the next UTC midnight.

Next steps

Authentication - key lifecycle, multiple keys, error responses for missing or invalid keys.

Rate limits and errors - plan quotas, 429 handling and retry strategy.

API Reference - all endpoints, grouped by direction, with try-it support.

1. Get an API key#

2. Make your first request#

curl#

Python (requests)#

JavaScript (fetch)#

3. Read the response#

4. Watch your rate-limit headers#

Next steps#